diff --git a/manual/v3.0.0/api/.buildinfo b/manual/v3.0.0/api/.buildinfo new file mode 100644 index 00000000..b44cc5e6 --- /dev/null +++ b/manual/v3.0.0/api/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 4a8b7ec45495f360c4537c54b3078b84 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/manual/v3.0.0/api/_modules/index.html b/manual/v3.0.0/api/_modules/index.html new file mode 100644 index 00000000..c31bb200 --- /dev/null +++ b/manual/v3.0.0/api/_modules/index.html @@ -0,0 +1,127 @@ + + + + + + + + Overview: module code — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Overview: module code
    • +
  • +
    • +
+
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/_info.html b/manual/v3.0.0/api/_modules/odatse/_info.html new file mode 100644 index 00000000..cc0ed366 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/_info.html @@ -0,0 +1,234 @@ + + + + + + + + odatse._info — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse._info

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import MutableMapping, Optional
+from pathlib import Path
+from fnmatch import fnmatch
+
+from .util import toml
+from . import mpi
+from . import exception
+
+
+

+[docs]
+class Info:
+    """
+    A class to represent the information structure for the data-analysis software.
+    """
+
+    base: dict
+    algorithm: dict
+    solver: dict
+    runner: dict
+
+

+[docs]
+    def __init__(self, d: Optional[MutableMapping] = None):
+        """
+        Initialize the Info object.
+
+        Parameters
+        ----------
+        d : MutableMapping (optional)
+            A dictionary to initialize the Info object.
+        """
+        if d is not None:
+            self.from_dict(d)
+        else:
+            self._cleanup()

+
+
+

+[docs]
+    def from_dict(self, d: MutableMapping) -> None:
+        """
+        Initialize the Info object from a dictionary.
+
+        Parameters
+        ----------
+        d : MutableMapping
+            A dictionary containing the information to initialize the Info object.
+
+        Raises
+        ------
+        exception.InputError
+            If any required section is missing in the input dictionary.
+        """
+        for section in ["base", "algorithm", "solver"]:
+            if section not in d:
+                raise exception.InputError(
+                    f"ERROR: section {section} does not appear in input"
+                )
+        self._cleanup()
+        self.base = d["base"]
+        self.algorithm = d["algorithm"]
+        self.solver = d["solver"]
+        self.runner = d.get("runner", {})
+
+        self.base["root_dir"] = (
+            Path(self.base.get("root_dir", ".")).expanduser().absolute()
+        )
+        self.base["output_dir"] = (
+            self.base["root_dir"]
+            / Path(self.base.get("output_dir", ".")).expanduser()
+        )

+
+
+

+[docs]
+    def _cleanup(self) -> None:
+        """
+        Reset the Info object to its default state.
+        """
+        self.base = {}
+        self.base["root_dir"] = Path(".").absolute()
+        self.base["output_dir"] = self.base["root_dir"]
+        self.algorithm = {}
+        self.solver = {}
+        self.runner = {}

+
+
+

+[docs]
+    @classmethod
+    def from_file(cls, file_name, fmt="", **kwargs):
+        """
+        Create an Info object from a file.
+
+        Parameters
+        ----------
+        file_name : str
+            The name of the file to load the information from.
+        fmt : str
+            The format of the file (default is "").
+        **kwargs
+            Additional keyword arguments.
+
+        Returns
+        -------
+        Info
+            An Info object initialized with the data from the file.
+
+        Raises
+        ------
+        ValueError
+            If the file format is unsupported.
+        """
+        if fmt == "toml" or fnmatch(file_name.lower(), "*.toml"):
+            inp = {}
+            if mpi.rank() == 0:
+                inp = toml.load(file_name)
+            if mpi.size() > 1:
+                inp = mpi.comm().bcast(inp, root=0)
+            return cls(inp)
+        else:
+            raise ValueError("unsupported file format: {}".format(file_name))

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/_initialize.html b/manual/v3.0.0/api/_modules/odatse/_initialize.html new file mode 100644 index 00000000..dd69279e --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/_initialize.html @@ -0,0 +1,161 @@ + + + + + + + + odatse._initialize — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse._initialize

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import odatse
+
+

+[docs]
+def initialize():
+    """
+    Initialize for main function by parsing commandline arguments and loading input files
+
+    Returns
+    -------
+    Tuple(Info, str)
+        an Info object having parameter values, and a run_mode string
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description=(
+            "Data-analysis software of quantum beam "
+            "diffraction experiments for 2D material structure"
+        )
+    )
+    parser.add_argument("inputfile", help="input file with TOML format")
+    parser.add_argument("--version", action="version", version=odatse.__version__)
+
+    mode_group = parser.add_mutually_exclusive_group()
+    mode_group.add_argument("--init", action="store_true", help="initial start (default)")
+    mode_group.add_argument("--resume", action="store_true", help="resume intterupted run")
+    mode_group.add_argument("--cont", action="store_true", help="continue from previous run")
+
+    parser.add_argument("--reset_rand", action="store_true", default=False, help="new random number series in resume or continue mode")
+
+    args = parser.parse_args()
+
+
+    if args.init is True:
+        run_mode = "initial"
+    elif args.resume is True:
+        run_mode = "resume"
+        if args.reset_rand is True:
+            run_mode = "resume-resetrand"
+    elif args.cont is True:
+        run_mode = "continue"
+        if args.reset_rand is True:
+            run_mode = "continue-resetrand"
+    else:
+        run_mode = "initial"  # default
+
+    info = odatse.Info.from_file(args.inputfile)
+    # info.algorithm.update({"run_mode": run_mode})
+
+    return info, run_mode

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/_main.html b/manual/v3.0.0/api/_modules/odatse/_main.html new file mode 100644 index 00000000..00de97a0 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/_main.html @@ -0,0 +1,139 @@ + + + + + + + + odatse._main — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse._main

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import sys
+import odatse
+
+

+[docs]
+def main():
+    """
+    Main function to run the data-analysis software for quantum beam diffraction experiments
+    on 2D material structures. It parses command-line arguments, loads the input file,
+    selects the appropriate algorithm and solver, and executes the analysis.
+    """
+
+    info, run_mode = odatse.initialize()
+
+    alg_module = odatse.algorithm.choose_algorithm(info.algorithm["name"])
+
+    solvername = info.solver["name"]
+    if solvername == "analytical":
+        from .solver.analytical import Solver
+    else:
+        if odatse.mpi.rank() == 0:
+            print(f"ERROR: Unknown solver ({solvername})")
+        sys.exit(1)
+
+    solver = Solver(info)
+    runner = odatse.Runner(solver, info)
+    alg = alg_module.Algorithm(info, runner, run_mode=run_mode)
+
+    result = alg.main()

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm.html b/manual/v3.0.0/api/_modules/odatse/algorithm.html new file mode 100644 index 00000000..60ed72ab --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm.html @@ -0,0 +1,144 @@ + + + + + + + + odatse.algorithm — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from ._algorithm import AlgorithmBase
+
+

+[docs]
+def choose_algorithm(name):
+    """
+    Search for algorithm module by name
+
+    Parameters
+    ----------
+    name : str
+        name of the algorithm
+
+    Returns
+    -------
+    module
+        algorithm module
+    """
+
+    alg_table = {
+        "mapper": "mapper_mpi",
+        "minsearch": "min_search",
+    }
+
+    try:
+        import importlib
+        alg_name = "odatse.algorithm.{}".format(alg_table.get(name, name))
+        alg_module = importlib.import_module(alg_name)
+    except ModuleNotFoundError as e:
+        print("ERROR: {}".format(e))
+        import sys
+        sys.exit(1)
+
+    return alg_module

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/_algorithm.html b/manual/v3.0.0/api/_modules/odatse/algorithm/_algorithm.html new file mode 100644 index 00000000..12fd50ba --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/_algorithm.html @@ -0,0 +1,535 @@ + + + + + + + + odatse.algorithm._algorithm — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm._algorithm

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+
+from abc import ABCMeta, abstractmethod
+from enum import IntEnum
+import time
+import os
+import pathlib
+import pickle
+import shutil
+import copy
+
+import numpy as np
+
+import odatse
+import odatse.util.limitation
+from odatse import exception, mpi
+
+# for type hints
+from pathlib import Path
+from typing import List, Optional, TYPE_CHECKING, Dict, Tuple
+
+
+if TYPE_CHECKING:
+    from mpi4py import MPI
+
+

+[docs]
+class AlgorithmStatus(IntEnum):
+    """Enumeration for the status of the algorithm."""
+    INIT = 1
+    PREPARE = 2
+    RUN = 3

+
+
+

+[docs]
+class AlgorithmBase(metaclass=ABCMeta):
+    """Base class for algorithms, providing common functionality and structure."""
+
+    mpicomm: Optional["MPI.Comm"]
+    mpisize: int
+    mpirank: int
+    rng: np.random.RandomState
+    dimension: int
+    label_list: List[str]
+    runner: Optional[odatse.Runner]
+
+    root_dir: Path
+    output_dir: Path
+    proc_dir: Path
+
+    timer: Dict[str, Dict]
+
+    status: AlgorithmStatus = AlgorithmStatus.INIT
+    mode: Optional[str] = None
+
+

+[docs]
+    @abstractmethod
+    def __init__(
+            self,
+            info: odatse.Info,
+            runner: Optional[odatse.Runner] = None,
+            run_mode: str = "initial"
+    ) -> None:
+        """
+        Initialize the algorithm with the given information and runner.
+
+        Parameters
+        ----------
+        info : Info
+            Information object containing algorithm and base parameters.
+        runner : Runner (optional)
+            Optional runner object to execute the algorithm.
+        run_mode : str
+            Mode in which the algorithm should run.
+        """
+        self.mpicomm = mpi.comm()
+        self.mpisize = mpi.size()
+        self.mpirank = mpi.rank()
+        self.timer = {"init": {}, "prepare": {}, "run": {}, "post": {}}
+        self.timer["init"]["total"] = 0.0
+        self.status = AlgorithmStatus.INIT
+        self.mode = run_mode.lower()
+
+        # keep copy of parameters
+        self.info = copy.deepcopy(info.algorithm)
+
+        self.dimension = info.algorithm.get("dimension") or info.base.get("dimension")
+        if not self.dimension:
+            raise ValueError("ERROR: dimension is not defined")
+
+        if "label_list" in info.algorithm:
+            label = info.algorithm["label_list"]
+            if len(label) != self.dimension:
+                raise ValueError(f"ERROR: length of label_list and dimension do not match ({len(label)} != {self.dimension})")
+            self.label_list = label
+        else:
+            self.label_list = [f"x{d+1}" for d in range(self.dimension)]
+
+        # initialize random number generator
+        self.__init_rng(info)
+
+        # directories
+        self.root_dir = info.base["root_dir"]
+        self.output_dir = info.base["output_dir"]
+        self.proc_dir = self.output_dir / str(self.mpirank)
+        self.proc_dir.mkdir(parents=True, exist_ok=True)
+        # Some cache of the filesystem may delay making a dictionary
+        # especially when mkdir just after removing the old one
+        while not self.proc_dir.is_dir():
+            time.sleep(0.1)
+        if self.mpisize > 1:
+            self.mpicomm.Barrier()
+
+        # checkpointing
+        self.checkpoint = info.algorithm.get("checkpoint", False)
+        self.checkpoint_file = info.algorithm.get("checkpoint_file", "status.pickle")
+        self.checkpoint_steps = info.algorithm.get("checkpoint_steps", 65536*256)  # large number
+        self.checkpoint_interval = info.algorithm.get("checkpoint_interval", 86400*360)  # longer enough
+
+        # runner
+        if runner is not None:
+            self.set_runner(runner)

+
+
+    def __init_rng(self, info: odatse.Info) -> None:
+        """
+        Initialize the random number generator.
+
+        Parameters
+        ----------
+        info : Info
+            Information object containing algorithm parameters.
+        """
+        seed = info.algorithm.get("seed", None)
+        seed_delta = info.algorithm.get("seed_delta", 314159)
+
+        if seed is None:
+            self.rng = np.random.RandomState()
+        else:
+            self.rng = np.random.RandomState(seed + self.mpirank * seed_delta)
+
+

+[docs]
+    def set_runner(self, runner: odatse.Runner) -> None:
+        """
+        Set the runner for the algorithm.
+
+        Parameters
+        ----------
+        runner : Runner
+            Runner object to execute the algorithm.
+        """
+        self.runner = runner

+
+
+

+[docs]
+    def prepare(self) -> None:
+        """
+        Prepare the algorithm for execution.
+        """
+        if self.runner is None:
+            msg = "Runner is not assigned"
+            raise RuntimeError(msg)
+        self._prepare()
+        self.status = AlgorithmStatus.PREPARE

+
+
+

+[docs]
+    @abstractmethod
+    def _prepare(self) -> None:
+        """Abstract method to be implemented by subclasses for preparation steps."""
+        pass

+
+
+

+[docs]
+    def run(self) -> None:
+        """
+        Run the algorithm.
+        """
+        if self.status < AlgorithmStatus.PREPARE:
+            msg = "algorithm has not prepared yet"
+            raise RuntimeError(msg)
+        original_dir = os.getcwd()
+        os.chdir(self.proc_dir)
+        self.runner.prepare(self.proc_dir)
+        self._run()
+        self.runner.post()
+        os.chdir(original_dir)
+        self.status = AlgorithmStatus.RUN

+
+
+

+[docs]
+    @abstractmethod
+    def _run(self) -> None:
+        """Abstract method to be implemented by subclasses for running steps."""
+        pass

+
+
+

+[docs]
+    def post(self) -> Dict:
+        """
+        Perform post-processing after the algorithm has run.
+
+        Returns
+        -------
+        Dict
+            Dictionary containing post-processing results.
+        """
+        if self.status < AlgorithmStatus.RUN:
+            msg = "algorithm has not run yet"
+            raise RuntimeError(msg)
+        original_dir = os.getcwd()
+        os.chdir(self.output_dir)
+        result = self._post()
+        os.chdir(original_dir)
+        return result

+
+
+

+[docs]
+    @abstractmethod
+    def _post(self) -> Dict:
+        """Abstract method to be implemented by subclasses for post-processing steps."""
+        pass

+
+
+

+[docs]
+    def main(self):
+        """
+        Main method to execute the algorithm.
+        """
+        time_sta = time.perf_counter()
+        self.prepare()
+        time_end = time.perf_counter()
+        self.timer["prepare"]["total"] = time_end - time_sta
+        if self.mpisize > 1:
+            self.mpicomm.Barrier()
+
+        time_sta = time.perf_counter()
+        self.run()
+        time_end = time.perf_counter()
+        self.timer["run"]["total"] = time_end - time_sta
+        print("end of run")
+        if self.mpisize > 1:
+            self.mpicomm.Barrier()
+
+        time_sta = time.perf_counter()
+        result = self.post()
+        time_end = time.perf_counter()
+        self.timer["post"]["total"] = time_end - time_sta
+
+        self.write_timer(self.proc_dir / "time.log")
+
+        return result

+
+
+

+[docs]
+    def write_timer(self, filename: Path):
+        """
+        Write the timing information to a file.
+
+        Parameters
+        ----------
+        filename : Path
+            Path to the file where timing information will be written.
+        """
+        with open(filename, "w") as fw:
+            fw.write("#in units of seconds\n")
+
+            def output_file(type):
+                d = self.timer[type]
+                fw.write("#{}\n total = {}\n".format(type, d["total"]))
+                for key, t in d.items():
+                    if key == "total":
+                        continue
+                    fw.write(" - {} = {}\n".format(key, t))
+
+            output_file("init")
+            output_file("prepare")
+            output_file("run")
+            output_file("post")

+
+
+

+[docs]
+    def _save_data(self, data, filename="state.pickle", ngen=3) -> None:
+        """
+        Save data to a file with versioning.
+
+        Parameters
+        ----------
+        data
+            Data to be saved.
+        filename
+            Name of the file to save the data.
+        ngen : int, default: 3
+            Number of generations for versioning.
+        """
+        try:
+            fn = Path(filename + ".tmp")
+            with open(fn, "wb") as f:
+                pickle.dump(data, f)
+        except Exception as e:
+            print("ERROR: {}".format(e))
+            sys.exit(1)
+
+        for idx in range(ngen-1, 0, -1):
+            fn_from = Path(filename + "." + str(idx))
+            fn_to = Path(filename + "." + str(idx+1))
+            if fn_from.exists():
+                shutil.move(fn_from, fn_to)
+        if ngen > 0:
+            if Path(filename).exists():
+                fn_to = Path(filename + "." + str(1))
+                shutil.move(Path(filename), fn_to)
+        shutil.move(Path(filename + ".tmp"), Path(filename))
+        print("save_state: write to {}".format(filename))

+
+
+

+[docs]
+    def _load_data(self, filename="state.pickle") -> Dict:
+        """
+        Load data from a file.
+
+        Parameters
+        ----------
+        filename
+            Name of the file to load the data from.
+
+        Returns
+        -------
+        Dict
+            Dictionary containing the loaded data.
+        """
+        if Path(filename).exists():
+            try:
+                fn = Path(filename)
+                with open(fn, "rb") as f:
+                    data = pickle.load(f)
+            except Exception as e:
+                print("ERROR: {}".format(e))
+                sys.exit(1)
+            print("load_state: load from {}".format(filename))
+        else:
+            print("ERROR: file {} not exist.".format(filename))
+            data = {}
+        return data

+
+
+

+[docs]
+    def _show_parameters(self):
+        """
+        Show the parameters of the algorithm.
+        """
+        if self.mpirank == 0:
+            info = flatten_dict(self.info)
+            for k, v in info.items():
+                print("{:16s}: {}".format(k, v))

+
+
+

+[docs]
+    def _check_parameters(self, param=None):
+        """
+        Check the parameters of the algorithm against previous parameters.
+
+        Parameters
+        ----------
+        param (optional)
+            Previous parameters to check against.
+        """
+        info = flatten_dict(self.info)
+        info_prev = flatten_dict(param)
+
+        for k,v in info.items():
+            w = info_prev.get(k, None)
+            if v != w:
+                if self.mpirank == 0:
+                    print("WARNING: parameter {} changed from {} to {}".format(k, w, v))
+            if self.mpirank == 0:
+                print("{:16s}: {}".format(k, v))

+

+
+
+# utility
+

+[docs]
+def flatten_dict(d, parent_key="", separator="."):
+    """
+    Flatten a nested dictionary.
+
+    Parameters
+    ----------
+    d
+        Dictionary to flatten.
+    parent_key : str, default : ""
+        Key for the parent dictionary.
+    separator : str, default : "."
+        Separator to use between keys.
+
+    Returns
+    -------
+    dict
+        Flattened dictionary.
+    """
+    items = []
+    if d:
+        for key_, val in d.items():
+            key = parent_key + separator + key_ if parent_key else key_
+            if isinstance(val, dict):
+                items.extend(flatten_dict(val, key, separator=separator).items())
+            else:
+                items.append((key, val))
+    return dict(items)

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/bayes.html b/manual/v3.0.0/api/_modules/odatse/algorithm/bayes.html new file mode 100644 index 00000000..a73077ba --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/bayes.html @@ -0,0 +1,447 @@ + + + + + + + + odatse.algorithm.bayes — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm.bayes

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List
+import time
+import shutil
+import copy
+from pathlib import Path
+
+import physbo
+import numpy as np
+
+import odatse
+import odatse.domain
+
+

+[docs]
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    """
+    A class to represent the Bayesian optimization algorithm.
+
+    Attributes
+    ----------
+    mesh_list : np.ndarray
+        The mesh grid list.
+    label_list : List[str]
+        The list of labels.
+    random_max_num_probes : int
+        The maximum number of random probes.
+    bayes_max_num_probes : int
+        The maximum number of Bayesian probes.
+    score : str
+        The scoring method.
+    interval : int
+        The interval for Bayesian optimization.
+    num_rand_basis : int
+        The number of random basis.
+    xopt : np.ndarray
+        The optimal solution.
+    best_fx : List[float]
+        The list of best function values.
+    best_action : List[int]
+        The list of best actions.
+    fx_list : List[float]
+        The list of function values.
+    param_list : List[np.ndarray]
+        The list of parameters.
+    """
+
+

+[docs]
+    def __init__(self, info: odatse.Info, runner: odatse.Runner = None, domain = None, run_mode: str = "initial") -> None:
+        """
+        Constructs all the necessary attributes for the Algorithm object.
+
+        Parameters
+        ----------
+        info : odatse.Info
+            The information object.
+        runner : odatse.Runner, optional
+            The runner object (default is None).
+        domain : optional
+            The domain object (default is None).
+        run_mode : str, optional
+            The run mode (default is "initial").
+        """
+        super().__init__(info=info, runner=runner, run_mode=run_mode)
+
+        info_param = info.algorithm.get("param", {})
+        info_bayes = info.algorithm.get("bayes", {})
+
+        for key in ("random_max_num_probes", "bayes_max_num_probes", "score", "interval", "num_rand_basis"):
+            if key in info_param and key not in info_bayes:
+                print(f"WARNING: algorithm.param.{key} is deprecated. Use algorithm.bayes.{key} .")
+                info_bayes[key] = info_param[key]
+
+        self.random_max_num_probes = info_bayes.get("random_max_num_probes", 20)
+        self.bayes_max_num_probes = info_bayes.get("bayes_max_num_probes", 40)
+        self.score = info_bayes.get("score", "TS")
+        self.interval = info_bayes.get("interval", 5)
+        self.num_rand_basis = info_bayes.get("num_rand_basis", 5000)
+
+        if self.mpirank == 0:
+            print("# parameter")
+            print(f"random_max_num_probes = {self.random_max_num_probes}")
+            print(f"bayes_max_num_probes = {self.bayes_max_num_probes}")
+            print(f"score = {self.score}")
+            print(f"interval = {self.interval}")
+            print(f"num_rand_basis = {self.num_rand_basis}")
+
+        if domain and isinstance(domain, odatse.domain.MeshGrid):
+            self.domain = domain
+        else:
+            self.domain = odatse.domain.MeshGrid(info)
+        self.mesh_list = np.array(self.domain.grid)
+
+        X_normalized = physbo.misc.centering(self.mesh_list[:, 1:])
+        comm = self.mpicomm if self.mpisize > 1 else None
+        self.policy = physbo.search.discrete.policy(test_X=X_normalized, comm=comm)
+
+        if "seed" in info.algorithm:
+            seed = info.algorithm["seed"]
+            self.policy.set_seed(seed)
+
+        self.file_history = "history.npz"
+        self.file_training = "training.npz"
+        self.file_predictor = "predictor.dump"

+
+
+

+[docs]
+    def _initialize(self):
+        """
+        Initializes the algorithm parameters and timers.
+        """
+        self.istep = 0
+        self.param_list = []
+        self.fx_list = []
+        self.timer["run"]["random_search"] = 0.0
+        self.timer["run"]["bayes_search"] = 0.0
+
+        self._show_parameters()

+
+
+

+[docs]
+    def _run(self) -> None:
+        """
+        Runs the Bayesian optimization process.
+        """
+        runner = self.runner
+        mesh_list = self.mesh_list
+
+        class simulator:
+            def __call__(self, action: np.ndarray) -> float:
+                """
+                Simulates the function evaluation for a given action.
+
+                Parameters
+                ----------
+                action : np.ndarray
+                    The action to be evaluated.
+
+                Returns
+                -------
+                float
+                    The negative function value.
+                """
+                a = int(action[0])
+                args = (a, 0)
+                x = mesh_list[a, 1:]
+                fx = runner.submit(x, args)
+                fx_list.append(fx)
+                param_list.append(mesh_list[a])
+                return -fx
+
+        if self.mode is None:
+            raise RuntimeError("mode unset")
+
+        restore_rng = not self.mode.endswith("-resetrand")
+
+        if self.mode.startswith("init"):
+            self._initialize()
+        elif self.mode.startswith("resume"):
+            self._load_state(self.checkpoint_file, mode="resume", restore_rng=restore_rng)
+        elif self.mode.startswith("continue"):
+            self._load_state(self.checkpoint_file, mode="continue", restore_rng=restore_rng)
+        else:
+            raise RuntimeError("unknown mode {}".format(self.mode))
+
+        fx_list = self.fx_list
+        param_list = self.param_list
+
+        if self.mode.startswith("init"):
+            time_sta = time.perf_counter()
+            res = self.policy.random_search(
+                max_num_probes=self.random_max_num_probes, simulator=simulator()
+            )
+            time_end = time.perf_counter()
+            self.timer["run"]["random_search"] = time_end - time_sta
+
+            if self.checkpoint:
+                self._save_state(self.checkpoint_file)
+        else:
+            if self.istep >= self.bayes_max_num_probes:
+                res = copy.deepcopy(self.policy.history)
+
+        next_checkpoint_step = self.istep + self.checkpoint_steps
+        next_checkpoint_time = time.time() + self.checkpoint_interval
+
+        while self.istep < self.bayes_max_num_probes:
+            intv = 0 if self.istep % self.interval == 0 else -1
+
+            time_sta = time.perf_counter()
+            res = self.policy.bayes_search(
+                max_num_probes=1,
+                simulator=simulator(),
+                score=self.score,
+                interval=intv,
+                num_rand_basis=self.num_rand_basis,
+            )
+            time_end = time.perf_counter()
+            self.timer["run"]["bayes_search"] += time_end - time_sta
+
+            self.istep += 1
+
+            if self.checkpoint:
+                time_now = time.time()
+                if self.istep >= next_checkpoint_step or time_now >= next_checkpoint_time:
+                    self.fx_list = fx_list
+                    self.param_list = param_list
+
+                    self._save_state(self.checkpoint_file)
+                    next_checkpoint_step = self.istep + self.checkpoint_steps
+                    next_checkpoint_time = time_now + self.checkpoint_interval
+
+        self.best_fx, self.best_action = res.export_all_sequence_best_fx()
+        self.xopt = mesh_list[int(self.best_action[-1]), 1:]
+        self.fx_list = fx_list
+        self.param_list = param_list
+
+        if self.checkpoint:
+            self._save_state(self.checkpoint_file)

+
+
+

+[docs]
+    def _prepare(self) -> None:
+        """
+        Prepares the algorithm for execution.
+        """
+        pass

+
+
+

+[docs]
+    def _post(self) -> None:
+        """
+        Finalizes the algorithm execution and writes the results to a file.
+        """
+        label_list = self.label_list
+        if self.mpirank == 0:
+            with open("BayesData.txt", "w") as file_BD:
+                file_BD.write("#step")
+                for label in label_list:
+                    file_BD.write(f" {label}")
+                file_BD.write(" fx")
+                for label in label_list:
+                    file_BD.write(f" {label}_action")
+                file_BD.write(" fx_action\n")
+
+                for step, fx in enumerate(self.fx_list):
+                    file_BD.write(str(step))
+                    best_idx = int(self.best_action[step])
+                    for v in self.mesh_list[best_idx][1:]:
+                        file_BD.write(f" {v}")
+                    file_BD.write(f" {-self.best_fx[step]}")
+
+                    for v in self.param_list[step][1:]:
+                        file_BD.write(f" {v}")
+                    file_BD.write(f" {fx}\n")
+            print("Best Solution:")
+            for x, y in zip(label_list, self.xopt):
+                print(x, "=", y)
+        return {"x": self.xopt, "fx": self.best_fx}

+
+
+

+[docs]
+    def _save_state(self, filename):
+        """
+        Saves the current state of the algorithm to a file.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file to save the state.
+        """
+        data = {
+            "mpisize": self.mpisize,
+            "mpirank": self.mpirank,
+            "rng": self.rng.get_state(),
+            "timer": self.timer,
+            "info": self.info,
+            "istep": self.istep,
+            "param_list": self.param_list,
+            "fx_list": self.fx_list,
+            "file_history": self.file_history,
+            "file_training": self.file_training,
+            "file_predictor": self.file_predictor,
+            "random_number": np.random.get_state(),
+        }
+        self._save_data(data, filename)
+
+        self.policy.save(file_history=Path(self.output_dir, self.file_history),
+                         file_training=Path(self.output_dir, self.file_training),
+                         file_predictor=Path(self.output_dir, self.file_predictor))

+
+
+

+[docs]
+    def _load_state(self, filename, mode="resume", restore_rng=True):
+        """
+        Loads the state of the algorithm from a file.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file to load the state from.
+        mode : str, optional
+            The mode to load the state (default is "resume").
+        restore_rng : bool, optional
+            Whether to restore the random number generator state (default is True).
+        """
+        data = self._load_data(filename)
+        if not data:
+            print("ERROR: Load status file failed")
+            sys.exit(1)
+
+        assert self.mpisize == data["mpisize"]
+        assert self.mpirank == data["mpirank"]
+
+        if restore_rng:
+            self.rng = np.random.RandomState()
+            self.rng.set_state(data["rng"])
+            np.random.set_state(data["random_number"])
+        self.timer = data["timer"]
+
+        info = data["info"]
+        self._check_parameters(info)
+
+        self.istep = data["istep"]
+        self.param_list = data["param_list"]
+        self.fx_list = data["fx_list"]
+
+        self.policy.load(file_history=Path(self.output_dir, self.file_history),
+                         file_training=Path(self.output_dir, self.file_training),
+                         file_predictor=Path(self.output_dir, self.file_predictor))

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/exchange.html b/manual/v3.0.0/api/_modules/odatse/algorithm/exchange.html new file mode 100644 index 00000000..93ee97cd --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/exchange.html @@ -0,0 +1,624 @@ + + + + + + + + odatse.algorithm.exchange — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm.exchange

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from io import open
+import copy
+import time
+import itertools
+import sys
+
+import numpy as np
+
+import odatse
+import odatse.algorithm.montecarlo
+from odatse.algorithm.montecarlo import read_Ts
+from odatse.util.separateT import separateT
+
+

+[docs]
+class Algorithm(odatse.algorithm.montecarlo.AlgorithmBase):
+    """Replica Exchange Monte Carlo
+
+    Attributes
+    ==========
+    x: np.ndarray
+        current configuration
+    inode: np.ndarray
+        current configuration index (discrete parameter space)
+    fx: np.ndarray
+        current "Energy"
+    Tindex: np.ndarray
+        current "Temperature" index
+    istep: int
+        current step (or, the number of calculated energies)
+    best_x: np.ndarray
+        best configuration
+    best_fx: float
+        best "Energy"
+    best_istep: int
+        index of best configuration
+    nreplica: int
+        The number of replicas (= the number of procs)
+    T2rep: np.ndarray
+        Mapping from temperature index to replica index
+    rep2T: np.ndarray
+        Reverse mapping from replica index to temperature index
+    exchange_direction: bool
+        Parity of exchange direction
+    """
+
+    x: np.ndarray
+    xmin: np.ndarray
+    xmax: np.ndarray
+    #xunit: np.ndarray
+    xstep: np.ndarray
+
+    numsteps: int
+    numsteps_exchange: int
+
+    fx: np.ndarray
+    istep: int
+    nreplica: int
+    Tindex: np.ndarray
+    rep2T: np.ndarray
+    T2rep: np.ndarray
+
+    exchange_direction: bool
+
+

+[docs]
+    def __init__(self,
+                 info: odatse.Info,
+                 runner: odatse.Runner = None,
+                 run_mode: str = "initial"
+    ) -> None:
+        """
+        Initialize the Algorithm class.
+
+        Parameters
+        ----------
+        info : odatse.Info
+            Information object containing algorithm parameters.
+        runner : odatse.Runner, optional
+            Runner object for executing the algorithm.
+        run_mode : str, optional
+            Mode to run the algorithm in, by default "initial".
+        """
+        time_sta = time.perf_counter()
+
+        info_exchange = info.algorithm["exchange"]
+        nwalkers = info_exchange.get("nreplica_per_proc", 1)
+
+        super().__init__(info=info, runner=runner, nwalkers=nwalkers, run_mode=run_mode)
+
+        self.nreplica = self.mpisize * self.nwalkers
+        self.input_as_beta, self.betas = read_Ts(info_exchange, numT=self.nreplica)
+
+        self.numsteps = info_exchange["numsteps"]
+        self.numsteps_exchange = info_exchange["numsteps_exchange"]
+        time_end = time.perf_counter()
+        self.timer["init"]["total"] = time_end - time_sta

+
+
+

+[docs]
+    def _print_info(self) -> None:
+        """
+        Print information about the algorithm.
+        """
+        if self.mpirank == 0:
+            pass
+        if self.mpisize > 1:
+            self.mpicomm.barrier()

+
+
+

+[docs]
+    def _initialize(self) -> None:
+        """
+        Initialize the algorithm parameters and state.
+        """
+        super()._initialize()
+
+        self.Tindex = np.arange(
+            self.mpirank * self.nwalkers, (self.mpirank + 1) * self.nwalkers
+        )
+        self.rep2T = np.arange(self.nreplica)
+        self.T2rep = np.arange(self.nreplica)
+
+        self.exchange_direction = True
+        self.istep = 0
+
+        self._show_parameters()

+
+
+

+[docs]
+    def _run(self) -> None:
+        """
+        Run the algorithm.
+        """
+        # print(">>> _run")
+
+        if self.mode is None:
+            raise RuntimeError("mode unset")
+
+        restore_rng = not self.mode.endswith("-resetrand")
+
+        if self.mode.startswith("init"):
+            self._initialize()
+        elif self.mode.startswith("resume"):
+            self._load_state(self.checkpoint_file, mode="resume", restore_rng=restore_rng)
+        elif self.mode.startswith("continue"):
+            self._load_state(self.checkpoint_file, mode="continue", restore_rng=restore_rng)
+        else:
+            raise RuntimeError("unknown mode {}".format(self.mode))
+
+        beta = self.betas[self.Tindex]
+
+        if self.mode.startswith("init"):
+            # first step
+            self._evaluate()
+
+            file_trial = open("trial.txt", "w")
+            self._write_result_header(file_trial)
+            self._write_result(file_trial)
+
+            file_result = open("result.txt", "w")
+            self._write_result_header(file_result)
+            self._write_result(file_result)
+
+            self.istep += 1
+
+            minidx = np.argmin(self.fx)
+            self.best_x = copy.copy(self.x[minidx, :])
+            self.best_fx = np.min(self.fx[minidx])
+            self.best_istep = 0
+            self.best_iwalker = 0
+        else:
+            file_trial = open("trial.txt", "a")
+            file_result = open("result.txt", "a")
+
+        next_checkpoint_step = self.istep + self.checkpoint_steps
+        next_checkpoint_time = time.time() + self.checkpoint_interval
+
+        while self.istep < self.numsteps:
+            # print(">>> istep={}".format(self.istep))
+
+            # Exchange
+            if self.istep % self.numsteps_exchange == 0:
+                # print(">>> do exchange")
+                time_sta = time.perf_counter()
+                if self.nreplica > 1:
+                    self._exchange(self.exchange_direction)
+                if self.nreplica > 2:
+                    self.exchange_direction = not self.exchange_direction
+                time_end = time.perf_counter()
+                self.timer["run"]["exchange"] += time_end - time_sta
+                beta = self.betas[self.Tindex]
+
+            # print(">>> call local_update")
+            self.local_update(beta, file_trial, file_result)
+            self.istep += 1
+
+            if self.checkpoint:
+                time_now = time.time()
+                if self.istep >= next_checkpoint_step or time_now >= next_checkpoint_time:
+                    self._save_state(self.checkpoint_file)
+                    next_checkpoint_step = self.istep + self.checkpoint_steps
+                    next_checkpoint_time = time_now + self.checkpoint_interval
+
+        file_result.close()
+        file_trial.close()
+        print("complete main process : rank {:08d}/{:08d}".format(self.mpirank, self.mpisize))
+
+        # store final state for continuation
+        if self.checkpoint:
+            # print(">>> store final state")
+            self._save_state(self.checkpoint_file)

+
+
+

+[docs]
+    def _exchange(self, direction: bool) -> None:
+        """
+        Try to exchange temperatures.
+
+        Parameters
+        ----------
+        direction : bool
+            Direction of the exchange.
+        """
+        if self.nwalkers == 1:
+            self.__exchange_single_walker(direction)
+        else:
+            self.__exchange_multi_walker(direction)

+
+
+    def __exchange_single_walker(self, direction: bool) -> None:
+        """
+        Exchange temperatures for a single walker.
+
+        Parameters
+        ----------
+        direction : bool
+            Direction of the exchange.
+        """
+        if self.mpisize > 1:
+            self.mpicomm.Barrier()
+        if direction:
+            if self.Tindex[0] % 2 == 0:
+                other_index = self.Tindex[0] + 1
+                is_main = True
+            else:
+                other_index = self.Tindex[0] - 1
+                is_main = False
+        else:
+            if self.Tindex[0] % 2 == 0:
+                other_index = self.Tindex[0] - 1
+                is_main = False
+            else:
+                other_index = self.Tindex[0] + 1
+                is_main = True
+
+        ibuf = np.zeros(1, dtype=np.int64)
+        fbuf = np.zeros(1, dtype=np.float64)
+
+        if 0 <= other_index < self.nreplica:
+            other_rank = self.T2rep[other_index]
+            if is_main:
+                self.mpicomm.Recv(fbuf, source=other_rank, tag=1)
+                other_fx = fbuf[0]
+                beta = self.betas[self.Tindex[0]]
+                other_beta = self.betas[self.Tindex[0] + 1]
+                logp = (other_beta - beta) * (other_fx - self.fx[0])
+                if logp >= 0.0 or self.rng.rand() < np.exp(logp):
+                    ibuf[0] = self.Tindex
+                    self.mpicomm.Send(ibuf, dest=other_rank, tag=2)
+                    self.Tindex[0] += 1
+                else:
+                    ibuf[0] = self.Tindex + 1
+                    self.mpicomm.Send(ibuf, dest=other_rank, tag=2)
+            else:
+                fbuf[0] = self.fx[0]
+                self.mpicomm.Send(fbuf, dest=other_rank, tag=1)
+                self.mpicomm.Recv(ibuf, source=other_rank, tag=2)
+                self.Tindex[0] = ibuf[0]
+
+        self.mpicomm.Barrier()
+        if self.mpirank == 0:
+            self.T2rep[self.Tindex[0]] = self.mpirank
+            for other_rank in range(1, self.nreplica):
+                self.mpicomm.Recv(ibuf, source=other_rank, tag=0)
+                self.T2rep[ibuf[0]] = other_rank
+        else:
+            ibuf[0] = self.Tindex
+            self.mpicomm.Send(ibuf, dest=0, tag=0)
+        self.mpicomm.Bcast(self.T2rep, root=0)
+
+    def __exchange_multi_walker(self, direction: bool) -> None:
+        """
+        Exchange temperatures for multiple walkers.
+
+        Parameters
+        ----------
+        direction : bool
+            Direction of the exchange.
+        """
+        comm = self.mpicomm
+        if self.mpisize > 1:
+            fx_all = comm.allgather(self.fx)
+            fx_all = np.array(fx_all).flatten()
+        else:
+            fx_all = self.fx
+
+        rep2T_diff = []
+        T2rep_diff = []
+
+        for irep in range(
+            self.mpirank * self.nwalkers, (self.mpirank + 1) * self.nwalkers
+        ):
+            iT = self.rep2T[irep]
+            if iT % 2 != 0:
+                continue
+            jT = iT + 1 if direction else iT - 1
+            if jT < 0 or jT == self.nreplica:
+                continue
+            jrep = self.T2rep[jT]
+            fdiff = fx_all[jrep] - fx_all[irep]
+            bdiff = self.betas[jT] - self.betas[iT]
+            logp = fdiff * bdiff
+            if logp >= 0.0 or self.rng.rand() < np.exp(logp):
+                rep2T_diff.append((irep, jT))  # this means self.rep2T[irep] = jT
+                rep2T_diff.append((jrep, iT))
+                T2rep_diff.append((iT, jrep))
+                T2rep_diff.append((jT, irep))
+
+        if self.mpisize > 1:
+            rep2T_diff = comm.allgather(rep2T_diff)
+            rep2T_diff = list(itertools.chain.from_iterable(rep2T_diff))  # flatten
+            T2rep_diff = comm.allgather(T2rep_diff)
+            T2rep_diff = list(itertools.chain.from_iterable(T2rep_diff))  # flatten
+
+        for diff in rep2T_diff:
+            self.rep2T[diff[0]] = diff[1]
+        for diff in T2rep_diff:
+            self.T2rep[diff[0]] = diff[1]
+        self.Tindex = self.rep2T[
+            self.mpirank * self.nwalkers : (self.mpirank + 1) * self.nwalkers
+        ]
+
+

+[docs]
+    def _prepare(self) -> None:
+        """
+        Prepare the algorithm for execution.
+        """
+        self.timer["run"]["submit"] = 0.0
+        self.timer["run"]["exchange"] = 0.0

+
+
+

+[docs]
+    def _post(self) -> None:
+        """
+        Post-process the results of the algorithm.
+        """
+        Ts = self.betas if self.input_as_beta else 1.0 / self.betas
+        if self.mpirank == 0:
+            print(f"start separateT {self.mpirank}")
+            sys.stdout.flush()
+        separateT(
+            Ts=Ts,
+            nwalkers=self.nwalkers,
+            output_dir=self.output_dir,
+            comm=self.mpicomm,
+            use_beta=self.input_as_beta,
+            buffer_size=10000,
+        )
+        if self.mpisize > 1:
+            # NOTE:
+            # ``gather`` seems not to work with many processes (say, 32) in some MPI implementation.
+            # ``Gather`` and ``allgather`` seem to work fine.
+            # Since the performance is not so important here, we use ``allgather`` for simplicity.
+            best_fx = self.mpicomm.allgather(self.best_fx)
+            best_x = self.mpicomm.allgather(self.best_x)
+            best_istep = self.mpicomm.allgather(self.best_istep)
+            best_iwalker = self.mpicomm.allgather(self.best_iwalker)
+        else:
+            best_fx = [self.best_fx]
+            best_x = [self.best_x]
+            best_istep = [self.best_istep]
+            best_iwalker = [self.best_iwalker]
+
+        best_rank = np.argmin(best_fx)
+
+        if self.mpirank == 0:
+            with open("best_result.txt", "w") as f:
+                f.write(f"nprocs = {self.nreplica}\n")
+                f.write(f"rank = {best_rank}\n")
+                f.write(f"step = {best_istep[best_rank]}\n")
+                f.write(f"walker = {best_iwalker[best_rank]}\n")
+                f.write(f"fx = {best_fx[best_rank]}\n")
+                for label, x in zip(self.label_list, best_x[best_rank]):
+                    f.write(f"{label} = {x}\n")
+            print("Best Result:")
+            print(f"  rank = {best_rank}")
+            print(f"  step = {best_istep[best_rank]}")
+            print(f"  walker = {best_iwalker[best_rank]}")
+            print(f"  fx = {best_fx[best_rank]}")
+            for label, x in zip(self.label_list, best_x[best_rank]):
+                print(f"  {label} = {x}")
+
+        return {
+            "x": best_x[best_rank],
+            "fx": best_fx[best_rank],
+            "nprocs": self.nreplica,
+            "rank": best_rank,
+            "step": best_istep[best_rank],
+            "walker": best_iwalker[best_rank],
+        }

+
+
+

+[docs]
+    def _save_state(self, filename) -> None:
+        """
+        Save the current state of the algorithm.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file to save the state to.
+        """
+        data = {
+            #-- _algorithm
+            "mpisize": self.mpisize,
+            "mpirank": self.mpirank,
+            "rng": self.rng.get_state(),
+            "timer": self.timer,
+            "info": self.info,
+            #-- montecarlo
+            "x": self.x,
+            "fx": self.fx,
+            "inode": self.inode,
+            "istep": self.istep,
+            "best_x": self.best_x,
+            "best_fx": self.best_fx,
+            "best_istep": self.best_istep,
+            "best_iwalker": self.best_iwalker,
+            "naccepted": self.naccepted,
+            "ntrial": self.ntrial,
+            #-- exchange
+            "nreplica": self.nreplica,
+            "Tindex": self.Tindex,
+            "rep2T": self.rep2T,
+            "T2rep": self.T2rep,
+            "exchange_direction": self.exchange_direction,
+        }
+        self._save_data(data, filename)

+
+
+

+[docs]
+    def _load_state(self, filename, mode="resume", restore_rng=True):
+        """
+        Load the state of the algorithm from a file.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file to load the state from.
+        mode : str, optional
+            The mode to load the state in, by default "resume".
+        restore_rng : bool, optional
+            Whether to restore the random number generator state, by default True.
+        """
+        data = self._load_data(filename)
+        if not data:
+            print("ERROR: Load status file failed")
+            sys.exit(1)
+
+        #-- _algorithm
+        assert self.mpisize == data["mpisize"]
+        assert self.mpirank == data["mpirank"]
+
+        if restore_rng:
+            self.rng = np.random.RandomState()
+            self.rng.set_state(data["rng"])
+        self.timer = data["timer"]
+
+        info = data["info"]
+        self._check_parameters(info)
+
+        #-- montecarlo
+        self.x = data["x"]
+        self.fx = data["fx"]
+        self.inode = data["inode"]
+
+        self.istep = data["istep"]
+
+        self.best_x = data["best_x"]
+        self.best_fx = data["best_fx"]
+        self.best_istep = data["best_istep"]
+        self.best_iwalker = data["best_iwalker"]
+
+        self.naccepted = data["naccepted"]
+        self.ntrial = data["ntrial"]
+
+        #-- exchange
+        assert self.nreplica == data["nreplica"]
+
+        self.Tindex = data["Tindex"]
+        self.rep2T = data["rep2T"]
+        self.T2rep = data["T2rep"]
+        self.exchange_direction = data["exchange_direction"]

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/mapper_mpi.html b/manual/v3.0.0/api/_modules/odatse/algorithm/mapper_mpi.html new file mode 100644 index 00000000..574cdeb5 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/mapper_mpi.html @@ -0,0 +1,370 @@ + + + + + + + + odatse.algorithm.mapper_mpi — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm.mapper_mpi

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List, Union, Dict
+
+from pathlib import Path
+from io import open
+import numpy as np
+import os
+import time
+
+import odatse
+import odatse.domain
+
+

+[docs]
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    """
+    Algorithm class for data analysis of quantum beam diffraction experiments.
+    Inherits from odatse.algorithm.AlgorithmBase.
+    """
+    mesh_list: List[Union[int, float]]
+
+

+[docs]
+    def __init__(self, info: odatse.Info,
+                 runner: odatse.Runner = None,
+                 domain = None,
+                 run_mode: str = "initial"
+    ) -> None:
+        """
+        Initialize the Algorithm instance.
+
+        Parameters
+        ----------
+        info : Info
+            Information object containing algorithm parameters.
+        runner : Runner
+            Optional runner object for submitting tasks.
+        domain :
+            Optional domain object, defaults to MeshGrid.
+        run_mode : str
+            Mode to run the algorithm, defaults to "initial".
+        """
+        super().__init__(info=info, runner=runner, run_mode=run_mode)
+
+        if domain and isinstance(domain, odatse.domain.MeshGrid):
+            self.domain = domain
+        else:
+            self.domain = odatse.domain.MeshGrid(info)
+
+        self.domain.do_split()
+        self.mesh_list = self.domain.grid_local
+
+        self.colormap_file = info.algorithm.get("colormap", "ColorMap.txt")
+        self.local_colormap_file = Path(self.colormap_file).name + ".tmp"

+
+
+

+[docs]
+    def _initialize(self) -> None:
+        """
+        Initialize the algorithm parameters and timer.
+        """
+        self.fx_list = []
+        self.timer["run"]["submit"] = 0.0
+        self._show_parameters()

+
+
+

+[docs]
+    def _run(self) -> None:
+        """
+        Execute the main algorithm process.
+        """
+        # Make ColorMap
+
+        if self.mode is None:
+            raise RuntimeError("mode unset")
+
+        if self.mode.startswith("init"):
+            self._initialize()
+        elif self.mode.startswith("resume"):
+            self._load_state(self.checkpoint_file)
+        else:
+            raise RuntimeError("unknown mode {}".format(self.mode))
+
+        # local colormap file
+        fp = open(self.local_colormap_file, "a")
+        if self.mode.startswith("init"):
+            fp.write("#" + " ".join(self.label_list) + " fval\n")
+
+        iterations = len(self.mesh_list)
+        istart = len(self.fx_list)
+
+        next_checkpoint_step = istart + self.checkpoint_steps
+        next_checkpoint_time = time.time() + self.checkpoint_interval
+
+        for icount in range(istart, iterations):
+            print("Iteration : {}/{}".format(icount+1, iterations))
+            mesh = self.mesh_list[icount]
+
+            # update information
+            args = (int(mesh[0]), 0)
+            x = np.array(mesh[1:])
+
+            time_sta = time.perf_counter()
+            fx = self.runner.submit(x, args)
+            time_end = time.perf_counter()
+            self.timer["run"]["submit"] += time_end - time_sta
+
+            self.fx_list.append([mesh[0], fx])
+
+            # write to local colormap file
+            fp.write(" ".join(
+                map(lambda v: "{:8f}".format(v), (*x, fx))
+            ) + "\n")
+
+            if self.checkpoint:
+                time_now = time.time()
+                if icount+1 >= next_checkpoint_step or time_now >= next_checkpoint_time:
+                    self._save_state(self.checkpoint_file)
+                    next_checkpoint_step = icount + 1 + self.checkpoint_steps
+                    next_checkpoint_time = time_now + self.checkpoint_interval
+
+        if iterations > 0:
+            opt_index = np.argsort(self.fx_list, axis=0)[0][1]
+            opt_id, opt_fx = self.fx_list[opt_index]
+            opt_mesh = self.mesh_list[opt_index]
+
+            self.opt_fx = opt_fx
+            self.opt_mesh = opt_mesh
+
+            print(f"[{self.mpirank}] minimum_value: {opt_fx:12.8e} at {opt_mesh[1:]} (mesh {opt_mesh[0]})")
+
+        self._output_results()
+
+        if Path(self.local_colormap_file).exists():
+            os.remove(Path(self.local_colormap_file))
+
+        print("complete main process : rank {:08d}/{:08d}".format(self.mpirank, self.mpisize))

+
+
+

+[docs]
+    def _output_results(self):
+        """
+        Output the results to the colormap file.
+        """
+        print("Make ColorMap")
+        time_sta = time.perf_counter()
+
+        with open(self.colormap_file, "w") as fp:
+            fp.write("#" + " ".join(self.label_list) + " fval\n")
+
+            for x, (idx, fx) in zip(self.mesh_list, self.fx_list):
+                fp.write(" ".join(
+                    map(lambda v: "{:8f}".format(v), (*x[1:], fx))
+                    ) + "\n")
+
+            if len(self.mesh_list) > 0:
+                fp.write("#Minimum point : " + " ".join(
+                    map(lambda v: "{:8f}".format(v), self.opt_mesh[1:])
+                ) + "\n")
+                fp.write("#R-factor : {:8f}\n".format(self.opt_fx))
+                fp.write("#see Log{:d}\n".format(round(self.opt_mesh[0])))
+            else:
+                fp.write("# No mesh point\n")
+
+        time_end = time.perf_counter()
+        self.timer["run"]["file_CM"] = time_end - time_sta

+
+
+

+[docs]
+    def _prepare(self) -> None:
+        """
+        Prepare the algorithm (no operation).
+        """
+        pass

+
+
+

+[docs]
+    def _post(self) -> Dict:
+        """
+        Post-process the results and gather data from all MPI ranks.
+
+        Returns
+        -------
+        Dict
+            Dictionary of results.
+        """
+        if self.mpisize > 1:
+            fx_lists = self.mpicomm.allgather(self.fx_list)
+            results = [v for vs in fx_lists for v in vs]
+        else:
+            results = self.fx_list
+
+        if self.mpirank == 0:
+            with open(self.colormap_file, "w") as fp:
+                for x, (idx, fx) in zip(self.domain.grid, results):
+                    assert x[0] == idx
+                    fp.write(" ".join(
+                        map(lambda v: "{:8f}".format(v), (*x[1:], fx))
+                    ) + "\n")
+
+        return {}

+
+
+

+[docs]
+    def _save_state(self, filename) -> None:
+        """
+        Save the current state of the algorithm to a file.
+
+        Parameters
+        ----------
+        filename
+            The name of the file to save the state to.
+        """
+        data = {
+            "mpisize": self.mpisize,
+            "mpirank": self.mpirank,
+            "timer": self.timer,
+            "info": self.info,
+            "fx_list": self.fx_list,
+            "mesh_size": len(self.mesh_list),
+        }
+        self._save_data(data, filename)

+
+
+

+[docs]
+    def _load_state(self, filename, restore_rng=True):
+        """
+        Load the state of the algorithm from a file.
+
+        Parameters
+        ----------
+        filename
+            The name of the file to load the state from.
+        restore_rng : bool
+            Whether to restore the random number generator state.
+        """
+        data = self._load_data(filename)
+        if not data:
+            print("ERROR: Load status file failed")
+            sys.exit(1)
+
+        assert self.mpisize == data["mpisize"]
+        assert self.mpirank == data["mpirank"]
+
+        self.timer = data["timer"]
+
+        info = data["info"]
+        self._check_parameters(info)
+
+        self.fx_list = data["fx_list"]
+
+        assert len(self.mesh_list) == data["mesh_size"]

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/min_search.html b/manual/v3.0.0/api/_modules/odatse/algorithm/min_search.html new file mode 100644 index 00000000..c085e1c5 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/min_search.html @@ -0,0 +1,388 @@ + + + + + + + + odatse.algorithm.min_search — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm.min_search

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List, Union
+import time
+
+import numpy as np
+import scipy
+from scipy.optimize import minimize
+
+import odatse
+import odatse.domain
+
+
+

+[docs]
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    """
+    Algorithm class for performing minimization using the Nelder-Mead method.
+    """
+
+    # inputs
+    label_list: np.ndarray
+    initial_list: np.ndarray
+    min_list: np.ndarray
+    max_list: np.ndarray
+    unit_list: np.ndarray
+
+    # hyperparameters of Nelder-Mead
+    initial_simplex_list: List[List[float]]
+    xtol: float
+    ftol: float
+
+    # results
+    xopt: np.ndarray
+    fopt: float
+    itera: int
+    funcalls: int
+    allvecs: List[np.ndarray]
+
+    iter_history: List[List[Union[int,float]]]
+    fev_history: List[List[Union[int,float]]]
+
+

+[docs]
+    def __init__(self, info: odatse.Info,
+                 runner: odatse.Runner = None,
+                 domain = None,
+                 run_mode: str = "initial"
+    ) -> None:
+        """
+        Initialize the Algorithm class.
+
+        Parameters
+        ----------
+        info : Info
+            Information object containing algorithm settings.
+        runner : Runner
+            Runner object for submitting jobs.
+        domain :
+            Domain object defining the search space.
+        run_mode : str
+            Mode of running the algorithm.
+        """
+        super().__init__(info=info, runner=runner, run_mode=run_mode)
+
+        if domain and isinstance(domain, odatse.domain.Region):
+            self.domain = domain
+        else:
+            self.domain = odatse.domain.Region(info)
+
+        self.min_list = self.domain.min_list
+        self.max_list = self.domain.max_list
+        self.unit_list = self.domain.unit_list
+
+        self.domain.initialize(rng=self.rng, limitation=runner.limitation, num_walkers=self.mpisize)
+        self.initial_list = self.domain.initial_list[self.mpirank]
+
+        info_minimize = info.algorithm.get("minimize", {})
+        self.initial_scale_list = info_minimize.get(
+            "initial_scale_list", [0.25] * self.dimension
+        )
+        self.xtol = info_minimize.get("xatol", 0.0001)
+        self.ftol = info_minimize.get("fatol", 0.0001)
+        self.maxiter = info_minimize.get("maxiter", 10000)
+        self.maxfev = info_minimize.get("maxfev", 100000)
+
+        self._show_parameters()

+
+
+

+[docs]
+    def _run(self) -> None:
+        """
+        Run the minimization algorithm.
+        """
+        run = self.runner
+
+        min_list = self.min_list
+        max_list = self.max_list
+        unit_list = self.unit_list
+        label_list = self.label_list
+
+        step = [0]
+        iter_history = []
+        fev_history = []
+
+        f0 = run.submit(self.initial_list, (0, 0))
+        iter_history.append([*self.initial_list, f0])
+
+        scipy_version = [int(s) for s in scipy.__version__.split('.')]
+
+        if scipy_version[0] >= 1 and scipy_version[1] >= 11:
+            def _cb(intermediate_result):
+                """
+                Callback function for scipy.optimize.minimize.
+                """
+                x = intermediate_result.x
+                fun = intermediate_result.fun
+                print("eval: x={}, fun={}".format(x, fun))
+                iter_history.append([*x, fun])
+        else:
+            def _cb(x):
+                """
+                Callback function for scipy.optimize.minimize.
+                """
+                fun = _f_calc(x, 1)
+                print("eval: x={}, fun={}".format(x, fun))
+                iter_history.append([*x, fun])
+
+        def _f_calc(x_list: np.ndarray, iset) -> float:
+            """
+            Calculate the objective function value.
+
+            Parameters
+            ----------
+            x_list : np.ndarray
+                List of variables.
+            iset :
+                Set index.
+
+            Returns
+            -------
+            float
+                Objective function value.
+            """
+            # check if within region -> boundary option in minimize
+            # note: 'bounds' option supported in scipy >= 1.7.0
+            in_range = np.all((min_list < x_list) & (x_list < max_list))
+            if not in_range:
+                print("Warning: out of range: {}".format(x_list))
+                return float("inf")
+
+            # check if limitation satisfied
+            in_limit = self.runner.limitation.judge(x_list)
+            if not in_limit:
+                print("Warning: variables do not satisfy the constraint formula")
+                return float("inf")
+
+            x_list /= unit_list
+
+            step[0] += 1
+            args = (step[0], iset)
+            y = run.submit(x_list, args)
+            if iset == 0:
+                fev_history.append([step[0], *x_list, y])
+            return y
+
+        time_sta = time.perf_counter()
+        optres = minimize(
+            _f_calc,
+            self.initial_list,
+            method="Nelder-Mead",
+            args=(0,),
+            # bounds=[(a,b) for a,b in zip(min_list, max_list)],
+            options={
+                "xatol": self.xtol,
+                "fatol": self.ftol,
+                "return_all": True,
+                "disp": True,
+                "maxiter": self.maxiter,
+                "maxfev": self.maxfev,
+                "initial_simplex": self.initial_simplex_list,
+            },
+            callback=_cb,
+        )
+
+        self.xopt = optres.x
+        self.fopt = optres.fun
+        self.itera = optres.nit
+        self.funcalls = optres.nfev
+        self.allvecs = optres.allvecs
+        time_end = time.perf_counter()
+        self.timer["run"]["min_search"] = time_end - time_sta
+
+        self.iter_history = iter_history
+        self.fev_history = fev_history
+
+        self._output_results()
+
+        if self.mpisize > 1:
+            self.mpicomm.barrier()

+
+
+

+[docs]
+    def _prepare(self):
+        """
+        Prepare the initial simplex for the Nelder-Mead algorithm.
+        """
+        # make initial simplex
+        #   [ v0, v0+a_1*e_1, v0+a_2*e_2, ... v0+a_d*e_d ]
+        # where a = ( a_1 a_2 a_3 ... a_d ) and e_k is a unit vector along k-axis
+        v = np.array(self.initial_list)
+        a = np.array(self.initial_scale_list)
+        self.initial_simplex_list = np.vstack((v, v + np.diag(a)))

+
+
+

+[docs]
+    def _output_results(self):
+        """
+        Output the results of the minimization to files.
+        """
+        label_list = self.label_list
+
+        with open("SimplexData.txt", "w") as fp:
+            fp.write("#step " + " ".join(label_list) + " R-factor\n")
+            for i, v in enumerate(self.iter_history):
+                fp.write(str(i) + " " + " ".join(map(str,v)) + "\n")
+
+        with open("History_FunctionCall.txt", "w") as fp:
+            fp.write("#No " + " ".join(label_list) + "\n")
+            for i, v in enumerate(self.fev_history):
+                fp.write(" ".join(map(str,v)) + "\n")
+
+        with open("res.txt", "w") as fp:
+            fp.write(f"fx = {self.fopt}\n")
+            for x, y in zip(label_list, self.xopt):
+                fp.write(f"{x} = {y}\n")
+            fp.write(f"iterations = {self.itera}\n")
+            fp.write(f"function_evaluations = {self.funcalls}\n")

+
+
+

+[docs]
+    def _post(self):
+        """
+        Post-process the results after minimization.
+        """
+        result = {
+            "x": self.xopt,
+            "fx": self.fopt,
+            "x0": self.initial_list,
+        }
+
+        if self.mpisize > 1:
+            results = self.mpicomm.allgather(result)
+        else:
+            results = [result]
+
+        xs = [v["x"] for v in results]
+        fxs = [v["fx"] for v in results]
+        x0s = [v["x0"] for v in results]
+
+        idx = np.argmin(fxs)
+
+        if self.mpirank == 0:
+            label_list = self.label_list
+            with open("res.txt", "w") as fp:
+                fp.write(f"fx = {fxs[idx]}\n")
+                for x, y in zip(label_list, xs[idx]):
+                    fp.write(f"{x} = {y}\n")
+                if len(results) > 1:
+                    fp.write(f"index = {idx}\n")
+                    for x, y in zip(label_list, x0s[idx]):
+                        fp.write(f"initial {x} = {y}\n")
+
+        return {"x": xs[idx], "fx": fxs[idx], "x0": x0s[idx]}

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/montecarlo.html b/manual/v3.0.0/api/_modules/odatse/algorithm/montecarlo.html new file mode 100644 index 00000000..81108970 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/montecarlo.html @@ -0,0 +1,622 @@ + + + + + + + + odatse.algorithm.montecarlo — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm.montecarlo

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import typing
+from typing import TextIO, Union, List, Tuple
+import copy
+import time
+from pathlib import Path
+
+import numpy as np
+
+import odatse
+from odatse.util.neighborlist import load_neighbor_list
+import odatse.util.graph
+import odatse.domain
+
+
+

+[docs]
+class AlgorithmBase(odatse.algorithm.AlgorithmBase):
+    """Base of Monte Carlo
+
+    Attributes
+    ==========
+    nwalkers: int
+        the number of walkers (per one process)
+    x: np.ndarray
+        current configurations
+        (NxD array, N is the number of walkers and D is the dimension)
+    fx: np.ndarray
+        current "Energy"s
+    istep: int
+        current step (or, the number of calculated energies)
+    best_x: np.ndarray
+        best configuration
+    best_fx: float
+        best "Energy"
+    best_istep: int
+        index of best configuration (step)
+    best_iwalker: int
+        index of best configuration (walker)
+    comm: MPI.comm
+        MPI communicator
+    rank: int
+        MPI rank
+    Ts: np.ndarray
+        List of temperatures
+    Tindex: np.ndarray
+        Temperature index
+    """
+
+    nwalkers: int
+
+    iscontinuous: bool
+
+    # continuous problem
+    x: np.ndarray
+    xmin: np.ndarray
+    xmax: np.ndarray
+    xstep: np.ndarray
+
+    # discrete problem
+    inode: np.ndarray
+    nnodes: int
+    node_coordinates: np.ndarray
+    neighbor_list: List[List[int]]
+    ncandidates: np.ndarray  # len(neighbor_list[i])-1
+
+    numsteps: int
+
+    fx: np.ndarray
+    istep: int
+    best_x: np.ndarray
+    best_fx: float
+    best_istep: int
+    best_iwalker: int
+    betas: np.ndarray
+    input_as_beta: bool
+    Tindex: np.ndarray
+
+    ntrial: int
+    naccepted: int
+
+

+[docs]
+    def __init__(self, info: odatse.Info,
+             runner: odatse.Runner = None,
+             domain = None,
+             nwalkers: int = 1,
+             run_mode: str = "initial") -> None:
+        """
+        Initialize the AlgorithmBase class.
+
+        Parameters
+        ----------
+        info : odatse.Info
+            Information object containing algorithm parameters.
+        runner : odatse.Runner, optional
+            Runner object for executing the algorithm (default is None).
+        domain : optional
+            Domain object defining the problem space (default is None).
+        nwalkers : int, optional
+            Number of walkers (default is 1).
+        run_mode : str, optional
+            Mode of the run, e.g., "initial" (default is "initial").
+        """
+        time_sta = time.perf_counter()
+        super().__init__(info=info, runner=runner, run_mode=run_mode)
+        self.nwalkers = nwalkers
+
+        if domain:
+            if isinstance(domain, odatse.domain.MeshGrid):
+                self.iscontinuous = False
+            elif isinstance(domain, odatse.domain.Region):
+                self.iscontinuous = True
+            else:
+                raise ValueError("ERROR: unsupoorted domain type {}".format(type(domain)))
+            self.domain = domain
+        else:
+            info_param = info.algorithm["param"]
+            if "mesh_path" in info_param:
+                self.iscontinuous = False
+                self.domain = odatse.domain.MeshGrid(info)
+            else:
+                self.iscontinuous = True
+                self.domain = odatse.domain.Region(info)
+
+        if self.iscontinuous:
+            self.xmin = self.domain.min_list
+            self.xmax = self.domain.max_list
+
+            if "step_list" in info_param:
+                self.xstep = info_param.get("step_list")
+
+            elif "unit_list" in info_param:
+                # for compatibility, unit_list can also be accepted for step size.
+                if self.mpirank == 0:
+                    print("WARNING: unit_list is obsolete. use step_list instead")
+                self.xstep = info_param.get("unit_list")
+            else:
+                # neither step_list nor unit_list is specified, report error.
+                # default value not assumed.
+                raise ValueError("ERROR: algorithm.param.step_list not specified")
+        else:
+            self.node_coordinates = np.array(self.domain.grid)[:, 1:]
+            self.nnodes = self.node_coordinates.shape[0]
+            self._setup_neighbour(info_param)
+
+        time_end = time.perf_counter()
+        self.timer["init"]["total"] = time_end - time_sta
+        self.Tindex = 0
+        self.input_as_beta = False

+
+
+

+[docs]
+    def _initialize(self):
+        """
+        Initialize the algorithm state.
+
+        This method sets up the initial state of the algorithm, including the
+        positions and energies of the walkers, and resets the counters for
+        accepted and trial steps.
+        """
+        if self.iscontinuous:
+            self.domain.initialize(rng=self.rng, limitation=self.runner.limitation, num_walkers=self.nwalkers)
+            self.x = self.domain.initial_list
+            self.inode = None
+        else:
+            self.inode = self.rng.randint(self.nnodes, size=self.nwalkers)
+            self.x = self.node_coordinates[self.inode, :]
+
+        self.fx = np.zeros(self.nwalkers)
+        self.best_fx = 0.0
+        self.best_istep = 0
+        self.best_iwalker = 0
+        self.naccepted = 0
+        self.ntrial = 0

+
+
+

+[docs]
+    def _setup_neighbour(self, info_param):
+        """
+        Set up the neighbor list for the discrete problem.
+
+        Parameters
+        ----------
+        info_param : dict
+            Dictionary containing algorithm parameters, including the path to the neighbor list file.
+
+        Raises
+        ------
+        ValueError
+            If the neighbor list path is not specified in the parameters.
+        RuntimeError
+            If the transition graph made from the neighbor list is not connected or not bidirectional.
+        """
+        if "neighborlist_path" in info_param:
+            nn_path = self.root_dir / Path(info_param["neighborlist_path"]).expanduser()
+            self.neighbor_list = load_neighbor_list(nn_path, nnodes=self.nnodes)
+
+            # checks
+            if not odatse.util.graph.is_connected(self.neighbor_list):
+                raise RuntimeError(
+                    "ERROR: The transition graph made from neighbor list is not connected."
+                    "\nHINT: Increase neighborhood radius."
+                )
+            if not odatse.util.graph.is_bidirectional(self.neighbor_list):
+                raise RuntimeError(
+                    "ERROR: The transition graph made from neighbor list is not bidirectional."
+                )
+
+            self.ncandidates = np.array([len(ns) - 1 for ns in self.neighbor_list], dtype=np.int64)
+        else:
+            raise ValueError(
+                "ERROR: Parameter algorithm.param.neighborlist_path does not exist."
+            )

+
+            # otherwise find neighbourlist
+
+
+

+[docs]
+    def _evaluate(self, in_range: np.ndarray = None) -> np.ndarray:
+        """
+        Evaluate the current "Energy"s.
+
+        This method overwrites `self.fx` with the result.
+
+        Parameters
+        ----------
+        in_range : np.ndarray, optional
+            Array indicating whether each walker is within the valid range (default is None).
+
+        Returns
+        -------
+        np.ndarray
+            Array of evaluated energies for the current configurations.
+        """
+        # print(">>> _evaluate")
+        for iwalker in range(self.nwalkers):
+            x = self.x[iwalker, :]
+            if in_range is None or in_range[iwalker]:
+                args = (self.istep, iwalker)
+
+                time_sta = time.perf_counter()
+                self.fx[iwalker] = self.runner.submit(x, args)
+                time_end = time.perf_counter()
+                self.timer["run"]["submit"] += time_end - time_sta
+            else:
+                self.fx[iwalker] = np.inf
+        return self.fx

+
+
+

+[docs]
+    def propose(self, current: np.ndarray) -> np.ndarray:
+        """
+        Propose the next candidate positions for the walkers.
+
+        Parameters
+        ----------
+        current : np.ndarray
+            Current positions of the walkers.
+
+        Returns
+        -------
+        proposed : np.ndarray
+            Proposed new positions for the walkers.
+        """
+        if self.iscontinuous:
+            dx = self.rng.normal(size=(self.nwalkers, self.dimension)) * self.xstep
+            proposed = current + dx
+        else:
+            proposed_list = [self.rng.choice(self.neighbor_list[i]) for i in current]
+            proposed = np.array(proposed_list, dtype=np.int64)
+        return proposed

+
+
+

+[docs]
+    def local_update(
+        self,
+        beta: Union[float, np.ndarray],
+        file_trial: TextIO,
+        file_result: TextIO,
+        extra_info_to_write: Union[List, Tuple] = None,
+    ):
+        """
+        one step of Monte Carlo
+
+        Parameters
+        ----------
+        beta: np.ndarray
+            inverse temperature for each walker
+        file_trial: TextIO
+            log file for all trial points
+        file_result: TextIO
+            log file for all generated samples
+        extra_info_to_write: List of np.ndarray or tuple of np.ndarray
+            extra information to write
+        """
+        # make candidate
+        x_old = copy.copy(self.x)
+        if self.iscontinuous:
+            self.x = self.propose(x_old)
+            #judgement of "in_range"
+            in_range_xmin = self.xmin <= self.x
+            in_range_xmax = self.x <= self.xmax
+            in_range_limitation = np.full(self.nwalkers, False)
+            for index_walker in range(self.nwalkers):
+                in_range_limitation[index_walker] = self.runner.limitation.judge(
+                                                        self.x[index_walker]
+                                                            )
+
+            in_range = (in_range_xmin & in_range_xmax).all(axis=1) \
+                       &in_range_limitation 
+        else:
+            i_old = copy.copy(self.inode)
+            self.inode = self.propose(self.inode)
+            self.x = self.node_coordinates[self.inode, :]
+            in_range = np.ones(self.nwalkers, dtype=bool)
+
+        # evaluate "Energy"s
+        fx_old = self.fx.copy()
+        self._evaluate(in_range)
+        self._write_result(file_trial, extra_info_to_write=extra_info_to_write)
+
+        fdiff = self.fx - fx_old
+
+        # Ignore an overflow warning in np.exp(x) for x >~ 710
+        # and an invalid operation warning in exp(nan) (nan came from 0 * inf)
+        # Note: fdiff (fx) becomes inf when x is out of range
+        # old_setting = np.seterr(over="ignore")
+        old_setting = np.seterr(all="ignore")
+        probs = np.exp(-beta * fdiff)
+        #probs[np.isnan(probs)] = 0.0
+        np.seterr(**old_setting)
+
+        if not self.iscontinuous:
+            probs *= self.ncandidates[i_old] / self.ncandidates[self.inode]
+        tocheck = in_range & (probs < 1.0)
+        num_check = np.count_nonzero(tocheck)
+
+        accepted = in_range.copy()
+        accepted[tocheck] = self.rng.rand(num_check) < probs[tocheck]
+        rejected = ~accepted
+        self.naccepted += accepted.sum()
+        self.ntrial += accepted.size
+
+        # revert rejected steps
+        self.x[rejected, :] = x_old[rejected, :]
+        self.fx[rejected] = fx_old[rejected]
+        if not self.iscontinuous:
+            self.inode[rejected] = i_old[rejected]
+
+        minidx = np.argmin(self.fx)
+        if self.fx[minidx] < self.best_fx:
+            np.copyto(self.best_x, self.x[minidx, :])
+            self.best_fx = self.fx[minidx]
+            self.best_istep = self.istep
+            self.best_iwalker = typing.cast(int, minidx)
+        self._write_result(file_result, extra_info_to_write=extra_info_to_write)

+
+
+

+[docs]
+    def _write_result_header(self, fp, extra_names=None) -> None:
+        """
+        Write the header for the result file.
+
+        Parameters
+        ----------
+        fp : TextIO
+            File pointer to the result file.
+        extra_names : list of str, optional
+            Additional column names to include in the header.
+        """
+        if self.input_as_beta:
+            fp.write("# step walker beta fx")
+        else:
+            fp.write("# step walker T fx")
+        for label in self.label_list:
+            fp.write(f" {label}")
+        if extra_names is not None:
+            for label in extra_names:
+                fp.write(f" {label}")
+        fp.write("\n")

+
+
+

+[docs]
+    def _write_result(self, fp, extra_info_to_write: Union[List, Tuple] = None) -> None:
+        """
+        Write the result of the current step to the file.
+
+        Parameters
+        ----------
+        fp : TextIO
+            File pointer to the result file.
+        extra_info_to_write : Union[List, Tuple], optional
+            Additional information to write for each walker (default is None).
+        """
+        for iwalker in range(self.nwalkers):
+            if isinstance(self.Tindex, int):
+                beta = self.betas[self.Tindex]
+            else:
+                beta = self.betas[self.Tindex[iwalker]]
+            fp.write(f"{self.istep}")
+            fp.write(f" {iwalker}")
+            if self.input_as_beta:
+                fp.write(f" {beta}")
+            else:
+                fp.write(f" {1.0/beta}")
+            fp.write(f" {self.fx[iwalker]}")
+            for x in self.x[iwalker, :]:
+                fp.write(f" {x}")
+            if extra_info_to_write is not None:
+                for ex in extra_info_to_write:
+                    fp.write(f" {ex[iwalker]}")
+            fp.write("\n")
+        fp.flush()

+

+
+

+[docs]
+def read_Ts(info: dict, numT: int = None) -> Tuple[bool, np.ndarray]:
+    """
+    Read temperature or inverse-temperature values from the provided info dictionary.
+
+    Parameters
+    ----------
+    info : dict
+        Dictionary containing temperature or inverse-temperature parameters.
+    numT : int, optional
+        Number of temperature or inverse-temperature values to generate (default is None).
+
+    Returns
+    -------
+    as_beta : bool
+        True if using inverse-temperature, False if using temperature.
+    betas : np.ndarray
+        Sequence of inverse-temperature values.
+
+    Raises
+    ------
+    ValueError
+        If numT is not specified, or if both Tmin/Tmax and bmin/bmax are defined, or if neither are defined,
+        or if bmin/bmax or Tmin/Tmax values are invalid.
+    RuntimeError
+        If the mode is unknown (neither set_T nor set_b).
+    """
+    if numT is None:
+        raise ValueError("read_Ts: numT is not specified")
+
+    Tmin = info.get("Tmin", None)
+    Tmax = info.get("Tmax", None)
+    bmin = info.get("bmin", None)
+    bmax = info.get("bmax", None)
+    logscale = info.get("Tlogspace", True)
+
+    if "Tinvspace" in info:
+        raise ValueError("Tinvspace is deprecated. Use bmax/bmin instead.")
+
+    set_b = (bmin is not None or bmax is not None)
+    set_T = (Tmin is not None or Tmax is not None)
+
+    if set_b and set_T:
+        raise ValueError("both Tmin/Tmax and bmin/bmax are defined")
+    if (not set_b) and (not set_T):
+        raise ValueError("neither Tmin/Tmax nor bmin/bmax are defined")
+
+    if set_b:
+        if bmin is None or bmax is None:
+            raise ValueError("bmin and bmax must be set")
+
+        input_as_beta = True
+        if not np.isreal(bmin) or bmin < 0.0:
+            raise ValueError("bmin must be zero or a positive real number")
+        if not np.isreal(bmax) or bmax < 0.0:
+            raise ValueError("bmin must be zero or a positive real number")
+        if bmin > bmax:
+            raise ValueError("bmin must be smaller than or equal to bmax")
+
+        if logscale:
+            if bmin == 0.0:
+                raise ValueError("bmin must be greater than 0.0 when Tlogspace is True")
+            betas = np.logspace(start=np.log10(bmin), stop=np.log10(bmax), num=numT)
+        else:
+            betas = np.linspace(start=bmin, stop=bmax, num=numT)
+
+    elif set_T:
+        if Tmin is None or Tmax is None:
+            raise ValueError("Tmin and Tmax must be set")
+
+        input_as_beta = False
+        if not np.isreal(Tmin) or Tmin <= 0.0:
+            raise ValueError("Tmin must be a positive real number")
+        if not np.isreal(Tmax) or Tmax <= 0.0:
+            raise ValueError("Tmax must be a positive real number")
+        if Tmin > Tmax:
+            raise ValueError("Tmin must be smaller than or equal to Tmax")
+
+        if logscale:
+            Ts = np.logspace(start=np.log10(Tmin), stop=np.log10(Tmax), num=numT)
+        else:
+            Ts = np.linspace(start=Tmin, stop=Tmax, num=numT)
+
+        betas = 1.0 / Ts
+    else:
+        raise RuntimeError("read_Ts: unknown mode: not set_T nor set_b")
+
+    return input_as_beta, betas

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/algorithm/pamc.html b/manual/v3.0.0/api/_modules/odatse/algorithm/pamc.html new file mode 100644 index 00000000..a156da82 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/algorithm/pamc.html @@ -0,0 +1,953 @@ + + + + + + + + odatse.algorithm.pamc — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.algorithm.pamc

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List, Dict, Union
+
+from io import open
+import copy
+import time
+import sys
+
+import numpy as np
+
+import odatse
+import odatse.exception
+import odatse.algorithm.montecarlo
+import odatse.util.separateT
+import odatse.util.resampling
+from odatse.algorithm.montecarlo import read_Ts
+
+
+

+[docs]
+class Algorithm(odatse.algorithm.montecarlo.AlgorithmBase):
+    """Population annealing Monte Carlo
+
+    Attributes
+    ==========
+    x: np.ndarray
+        current configuration
+    fx: np.ndarray
+        current "Energy"
+    logweights: np.ndarray
+        current logarithm of weights (Neal-Jarzynski factor)
+    istep: int
+        current step (or, the number of calculated energies)
+    best_x: np.ndarray
+        best configuration
+    best_fx: float
+        best "Energy"
+    best_istep: int
+        index of best configuration
+    comm: MPI.comm
+        MPI communicator
+    nreplica: int
+        The number of replicas (= the number of procs)
+    rank: int
+        MPI rank
+    betas: list
+        List of inverse temperatures
+    Tindex: int
+        Temperature index
+    """
+
+    x: np.ndarray
+    xmin: np.ndarray
+    xmax: np.ndarray
+    #xunit: np.ndarray
+    xstep: np.ndarray
+
+    numsteps: int
+    numsteps_annealing: int
+
+    logweights: np.ndarray
+    fx: np.ndarray
+    istep: int
+    nreplicas: np.ndarray
+    betas: np.ndarray
+    Tindex: int
+
+    fx_from_reset: np.ndarray
+
+    # 0th column: number of accepted MC trials
+    # 1st column: number of total MC trials
+    naccepted_from_reset: np.ndarray
+    resampling_interval: int
+
+    nset_bootstrap: int
+
+    walker_ancestors: np.ndarray
+    populations: np.ndarray
+    family_lo: int
+    family_hi: int
+
+    Fmeans: np.ndarray
+    Ferrs: np.ndarray
+
+

+[docs]
+    def __init__(self,
+                 info: odatse.Info,
+                 runner: odatse.Runner = None,
+                 run_mode: str = "initial"
+    ) -> None:
+        """
+        Initialize the Algorithm class.
+
+        Parameters
+        ----------
+        info : odatse.Info
+            Information object containing algorithm parameters.
+        runner : odatse.Runner, optional
+            Runner object for executing the algorithm, by default None.
+        run_mode : str, optional
+            Mode in which to run the algorithm, by default "initial".
+        """
+        time_sta = time.perf_counter()
+
+        info_pamc = info.algorithm["pamc"]
+        nwalkers = info_pamc.get("nreplica_per_proc", 1)
+
+        super().__init__(info=info, runner=runner, nwalkers=nwalkers, run_mode=run_mode)
+
+        self.verbose = True and self.mpirank == 0
+
+        numT = self._find_scheduling(info_pamc)
+
+        self.input_as_beta, self.betas = read_Ts(info_pamc, numT=numT)
+        self.betas.sort()
+
+        self.fix_nwalkers = info_pamc.get("fix_num_replicas", True)
+        self.resampling_interval = info_pamc.get("resampling_interval", 1)
+        if self.resampling_interval < 1:
+            self.resampling_interval = numT + 1
+
+        time_end = time.perf_counter()
+        self.timer["init"]["total"] = time_end - time_sta

+
+
+

+[docs]
+    def _initialize(self) -> None:
+        super()._initialize()
+
+        numT = len(self.betas)
+
+        self.logZ = 0.0
+        self.logZs = np.zeros(numT)
+        self.logweights = np.zeros(self.nwalkers)
+
+        self.Fmeans = np.zeros(numT)
+        self.Ferrs = np.zeros(numT)
+        nreplicas = self.mpisize * self.nwalkers
+        self.nreplicas = np.full(numT, nreplicas)
+
+        self.populations = np.zeros((numT, self.nwalkers), dtype=int)
+        self.family_lo = self.nwalkers * self.mpirank
+        self.family_hi = self.nwalkers * (self.mpirank + 1)
+        self.walker_ancestors = np.arange(self.family_lo, self.family_hi)
+        self.fx_from_reset = np.zeros((self.resampling_interval, self.nwalkers))
+        self.naccepted_from_reset = np.zeros((self.resampling_interval, 2), dtype=int)
+        self.acceptance_ratio = np.zeros(numT)
+
+        self._show_parameters()

+
+
+

+[docs]
+    def _find_scheduling(self, info_pamc) -> int:
+        """
+        Determine the scheduling for the algorithm based on the provided parameters.
+
+        Parameters
+        ----------
+        info_pamc : dict
+            Dictionary containing the parameters for the PAMC algorithm.
+
+        Returns
+        -------
+        int
+            The number of temperature steps (numT) determined from the input parameters.
+        """
+        numsteps = info_pamc.get("numsteps", 0)
+        numsteps_annealing = info_pamc.get("numsteps_annealing", 0)
+        numT = info_pamc.get("Tnum", 0)
+
+        oks = np.array([numsteps, numsteps_annealing, numT]) > 0
+        if np.count_nonzero(oks) != 2:
+            msg = "ERROR: Two of 'numsteps', 'numsteps_annealing', "
+            msg += "and 'Tnum' should be positive in the input file\n"
+            msg += f"  numsteps = {numsteps}\n"
+            msg += f"  numsteps_annealing = {numsteps_annealing}\n"
+            msg += f"  Tnum = {numT}\n"
+            raise odatse.exception.InputError(msg)
+
+        if numsteps <= 0:
+            self.numsteps_for_T = np.full(numT, numsteps_annealing)
+        elif numsteps_annealing <= 0:
+            nr = numsteps // numT
+            self.numsteps_for_T = np.full(numT, nr)
+            rem = numsteps - nr * numT
+            if rem > 0:
+                self.numsteps_for_T[0 : (rem - 1)] += 1
+        else:
+            ss: List[int] = []
+            while numsteps > 0:
+                if numsteps > numsteps_annealing:
+                    ss.append(numsteps_annealing)
+                    numsteps -= numsteps_annealing
+                else:
+                    ss.append(numsteps)
+                    numsteps = 0
+            self.numsteps_for_T = np.array(ss)
+            numT = len(ss)
+
+        return numT

+
+
+

+[docs]
+    def _run(self) -> None:
+
+        if self.mode is None:
+            raise RuntimeError("mode unset")
+
+        restore_rng = not self.mode.endswith("-resetrand")
+        if self.mode.startswith("init"):
+            self._initialize()
+
+            self.Tindex = 0
+            self.index_from_reset = 0
+            self.istep = 0
+
+            beta = self.betas[self.Tindex]
+            self._evaluate()
+
+            file_trial = open("trial_T0.txt", "w")
+            self._write_result_header(file_trial, ["weight", "ancestor"])
+            self._write_result(file_trial, [np.exp(self.logweights), self.walker_ancestors])
+            file_trial.close()
+
+            file_result = open("result_T0.txt", "w")
+            self._write_result_header(file_result, ["weight", "ancestor"])
+            self._write_result(file_result, [np.exp(self.logweights), self.walker_ancestors])
+            file_result.close()
+
+            self.istep += 1
+
+            minidx = np.argmin(self.fx)
+            self.best_x = copy.copy(self.x[minidx, :])
+            self.best_fx = np.min(self.fx[minidx])
+            self.best_istep = 0
+            self.best_iwalker = 0
+
+        elif self.mode.startswith("resume"):
+            self._load_state(self.checkpoint_file, mode="resume", restore_rng=restore_rng)
+
+        elif self.mode.startswith("continue"):
+            self._load_state(self.checkpoint_file, mode="continue", restore_rng=restore_rng)
+
+            Tindex = self.Tindex
+
+            dbeta = self.betas[Tindex + 1] - self.betas[Tindex]
+            self.logweights += -dbeta * self.fx
+            if self.index_from_reset == self.resampling_interval:
+                time_sta = time.perf_counter()
+                self._resample()
+                time_end = time.perf_counter()
+                self.timer["run"]["resampling"] += time_end - time_sta
+                self.index_from_reset = 0
+
+            self.Tindex += 1
+
+        else:
+            raise RuntimeError("unknown mode {}".format(self.mode))
+
+        next_checkpoint_step = self.istep + self.checkpoint_steps
+        next_checkpoint_time = time.time() + self.checkpoint_interval
+
+        if self.verbose:
+            print("\u03b2 mean[f] Err[f] nreplica log(Z/Z0) acceptance_ratio")
+
+        numT = len(self.betas)
+        while self.Tindex < numT:
+            # print(">>> Tindex = {}".format(self.Tindex))
+            Tindex = self.Tindex
+            beta = self.betas[self.Tindex]
+
+            if Tindex == 0:
+                file_trial = open(f"trial_T{Tindex}.txt", "a")
+                file_result = open(f"result_T{Tindex}.txt", "a")
+            else:  # Tindex=1,2,...
+                file_trial = open(f"trial_T{Tindex}.txt", "w")
+                self._write_result_header(file_trial, ["weight", "ancestor"])
+                file_result = open(f"result_T{Tindex}.txt", "w")
+                self._write_result_header(file_result, ["weight", "ancestor"])
+
+            if self.nwalkers != 0:
+                for _ in range(self.numsteps_for_T[Tindex]):
+                    self.local_update(
+                        beta,
+                        file_trial,
+                        file_result,
+                        extra_info_to_write=[
+                            np.exp(self.logweights),
+                            self.walker_ancestors,
+                        ],
+                    )
+                    self.istep += 1
+            else : #self.nwalkers == 0
+                pass
+
+            file_trial.close()
+            file_result.close()
+
+            # print(">>> istep={}".format(self.istep))
+
+            self.fx_from_reset[self.index_from_reset, :] = self.fx[:]
+            self.naccepted_from_reset[self.index_from_reset, 0] = self.naccepted
+            self.naccepted_from_reset[self.index_from_reset, 1] = self.ntrial
+            self.naccepted = 0
+            self.ntrial = 0
+            self.index_from_reset += 1
+
+            if Tindex == numT - 1:
+                break
+
+            dbeta = self.betas[Tindex + 1] - self.betas[Tindex]
+            self.logweights += -dbeta * self.fx
+            if self.index_from_reset == self.resampling_interval:
+                time_sta = time.perf_counter()
+                self._resample()
+                time_end = time.perf_counter()
+                self.timer["run"]["resampling"] += time_end - time_sta
+                self.index_from_reset = 0
+
+            self.Tindex += 1
+
+            if self.checkpoint:
+                time_now = time.time()
+                if self.istep >= next_checkpoint_step or time_now >= next_checkpoint_time:
+                    print(">>> checkpoint")
+                    self._save_state(self.checkpoint_file)
+                    next_checkpoint_step = self.istep + self.checkpoint_steps
+                    next_checkpoint_time = time_now + self.checkpoint_interval
+
+        # store final state for continuation
+        if self.checkpoint:
+            print(">>> store final state")
+            self._save_state(self.checkpoint_file)
+
+        if self.index_from_reset > 0:
+            res = self._gather_information(self.index_from_reset)
+            self._save_stats(res)
+        file_result.close()
+        file_trial.close()
+
+        if self.mpisize > 1:
+            self.mpicomm.barrier()
+        print("complete main process : rank {:08d}/{:08d}".format(self.mpirank, self.mpisize))

+
+
+

+[docs]
+    def _gather_information(self, numT: int = None) -> Dict[str, np.ndarray]:
+        """
+        Gather status information of each process
+
+        Parameters
+        ---------
+        numT : int
+            size of dataset
+
+        Returns
+        -------
+        res : Dict[str, np.ndarray]
+            key-value corresponding is the following
+
+            - fxs
+                - objective function of each walker over all processes
+            - logweights
+                - log of weights
+            - ns
+                - number of walkers in each process
+            - ancestors
+                - ancestor (origin) of each walker
+            - acceptance ratio
+                - acceptance_ratio for each temperature
+        """
+
+        if numT is None:
+            numT = self.resampling_interval
+        res = {}
+        if self.mpisize > 1:
+            fxs_list = self.mpicomm.allgather(self.fx_from_reset[0:numT, :])
+            fxs = np.block(fxs_list)
+            res["fxs"] = fxs
+            ns = np.array([fs.shape[1] for fs in fxs_list], dtype=int)
+            res["ns"] = ns
+            ancestors_list = self.mpicomm.allgather(self.walker_ancestors)
+            res["ancestors"] = np.block(ancestors_list)
+
+            naccepted = self.mpicomm.allreduce(self.naccepted_from_reset[0:numT, :])
+            res["acceptance ratio"] = naccepted[:, 0] / naccepted[:, 1]
+        else:
+            res["fxs"] = self.fx_from_reset[0:numT, :]
+            res["ns"] = np.array([self.nwalkers], dtype=int)
+            res["ancestors"] = self.walker_ancestors
+            res["acceptance ratio"] = (
+                self.naccepted_from_reset[:, 0] / self.naccepted_from_reset[:, 1]
+            )
+        fxs = res["fxs"]
+        numT, nreplicas = fxs.shape
+        endTindex = self.Tindex + 1
+        startTindex = endTindex - numT
+        logweights = np.zeros((numT, nreplicas))
+        for iT in range(1, numT):
+            dbeta = self.betas[startTindex + iT] - self.betas[startTindex + iT - 1]
+            logweights[iT, :] = logweights[iT - 1, :] - dbeta * fxs[iT - 1, :]
+        res["logweights"] = logweights
+        return res

+
+
+

+[docs]
+    def _save_stats(self, info: Dict[str, np.ndarray]) -> None:
+        """
+        Save statistical information from the algorithm run.
+
+        Parameters
+        ----------
+        info : Dict[str, np.ndarray]
+            Dictionary containing the following keys:
+            - fxs: Objective function of each walker over all processes.
+            - logweights: Logarithm of weights.
+            - ns: Number of walkers in each process.
+            - ancestors: Ancestor (origin) of each walker.
+            - acceptance ratio: Acceptance ratio for each temperature.
+        """
+        fxs = info["fxs"]
+        numT, nreplicas = fxs.shape
+        endTindex = self.Tindex + 1
+        startTindex = endTindex - numT
+
+        logweights = info["logweights"]
+        weights = np.exp(
+            logweights - logweights.max(axis=1).reshape(-1, 1)
+        )  # to avoid overflow
+
+        # Bias-corrected jackknife resampling method
+        fs = np.zeros((numT, nreplicas))
+        fw_sum = (fxs * weights).sum(axis=1)
+        w_sum = weights.sum(axis=1)
+        for i in range(nreplicas):
+            F = fw_sum - fxs[:, i] * weights[:, i]
+            W = w_sum - weights[:, i]
+            fs[:, i] = F / W
+        N = fs.shape[1]
+        fm = N * (fw_sum / w_sum) - (N - 1) * fs.mean(axis=1)
+        ferr = np.sqrt((N - 1) * fs.var(axis=1))
+
+        self.Fmeans[startTindex:endTindex] = fm
+        self.Ferrs[startTindex:endTindex] = ferr
+        self.nreplicas[startTindex:endTindex] = nreplicas
+        self.acceptance_ratio[startTindex:endTindex] = info["acceptance ratio"][0:numT]
+
+        weights = np.exp(logweights)
+        logz = np.log(np.mean(weights, axis=1))
+        self.logZs[startTindex:endTindex] = self.logZ + logz
+        if endTindex < len(self.betas):
+            # Calculate the next weight before reset and evaluate dF
+            bdiff = self.betas[endTindex] - self.betas[endTindex - 1]
+            w = np.exp(logweights[-1, :] - bdiff * fxs[-1, :])
+            self.logZ = self.logZs[startTindex] + np.log(w.mean())
+
+        if self.verbose:
+            for iT in range(startTindex, endTindex):
+                print(" ".join(map(str, [
+                    self.betas[iT],
+                    self.Fmeans[iT],
+                    self.Ferrs[iT],
+                    self.nreplicas[iT],
+                    self.logZs[iT],
+                    self.acceptance_ratio[iT],
+                ])))

+
+
+

+[docs]
+    def _resample(self) -> None:
+        """
+        Perform the resampling of walkers.
+
+        This method gathers information, saves statistical data, and performs resampling
+        using either fixed or varied weights. The method ensures that the algorithm
+        maintains a balanced set of walkers across different temperature steps.
+        """
+        res = self._gather_information()
+        self._save_stats(res)
+
+        # weights for resampling
+        dbeta = self.betas[self.Tindex + 1] - self.betas[self.Tindex]
+        logweights = res["logweights"][-1, :] - dbeta * res["fxs"][-1, :]
+        weights = np.exp(logweights - logweights.max())  # to avoid overflow
+        if self.fix_nwalkers:
+            self._resample_fixed(weights)
+            self.logweights[:] = 0.0
+        else:
+            ns = res["ns"]
+            offsets = ns.cumsum()
+            offset = offsets[self.mpirank - 1] if self.mpirank > 0 else 0
+            self._resample_varied(weights, offset)
+            self.fx_from_reset = np.zeros((self.resampling_interval, self.nwalkers))
+            self.logweights = np.zeros(self.nwalkers)

+
+
+

+[docs]
+    def _resample_varied(self, weights: np.ndarray, offset: int) -> None:
+        """
+        Perform resampling with varied weights.
+
+        This method resamples the walkers based on the provided weights and updates
+        the state of the algorithm accordingly.
+
+        Parameters
+        ----------
+        weights : np.ndarray
+            Array of weights for resampling.
+        offset : int
+            Offset for the weights array.
+        """
+        weights_sum = np.sum(weights)
+        expected_numbers = (self.nreplicas[0] / weights_sum) * weights[
+            offset : offset + self.nwalkers
+        ]
+        next_numbers = self.rng.poisson(expected_numbers)
+
+        if self.iscontinuous:
+            new_x = []
+            new_fx = []
+            new_ancestors = []
+            for iwalker in range(self.nwalkers):
+                for _ in range(next_numbers[iwalker]):
+                    new_x.append(self.x[iwalker, :])
+                    new_fx.append(self.fx[iwalker])
+                    new_ancestors.append(self.walker_ancestors[iwalker])
+            self.x = np.array(new_x)
+            self.fx = np.array(new_fx)
+            self.walker_ancestors = np.array(new_ancestors)
+        else:
+            new_inodes = []
+            new_fx = []
+            new_ancestors = []
+            for iwalker in range(self.nwalkers):
+                for _ in range(next_numbers[iwalker]):
+                    new_inodes.append(self.inodes[iwalker])
+                    new_fx.append(self.fx[iwalker])
+                    new_ancestors.append(self.walker_ancestors[iwalker])
+            self.inode = np.array(new_inodes)
+            self.fx = np.array(new_fx)
+            self.walker_ancestors = np.array(new_ancestors)
+            self.x = self.node_coordinates[self.inode, :]
+        self.nwalkers = np.sum(next_numbers)

+
+
+

+[docs]
+    def _resample_fixed(self, weights: np.ndarray) -> None:
+        """
+        Perform resampling with fixed weights.
+
+        This method resamples the walkers based on the provided weights and updates
+        the state of the algorithm accordingly.
+
+        Parameters
+        ----------
+        weights : np.ndarray
+            Array of weights for resampling.
+        """
+        resampler = odatse.util.resampling.WalkerTable(weights)
+        new_index = resampler.sample(self.rng, self.nwalkers)
+
+        if self.iscontinuous:
+            if self.mpisize > 1:
+                xs = np.zeros((self.mpisize, self.nwalkers, self.dimension))
+                self.mpicomm.Allgather(self.x, xs)
+                xs = xs.reshape(self.nreplicas[self.Tindex], self.dimension)
+                ancestors = np.array(
+                    self.mpicomm.allgather(self.walker_ancestors)
+                ).flatten()
+            else:
+                xs = self.x
+                ancestors = self.walker_ancestors
+            self.x = xs[new_index, :]
+            self.walker_ancestors = ancestors[new_index]
+        else:
+            if self.mpisize > 1:
+                inodes = np.array(self.mpicomm.allgather(self.inode)).flatten()
+                ancestors = np.array(
+                    self.mpicomm.allgather(self.walker_ancestors)
+                ).flatten()
+            else:
+                inodes = self.inode
+                ancestors = self.walker_ancestors
+            self.inode = inodes[new_index]
+            self.walker_ancestors = ancestors[new_index]
+            self.x = self.node_coordinates[self.inode, :]

+
+
+

+[docs]
+    def _prepare(self) -> None:
+        """
+        Prepare the algorithm for execution.
+
+        This method initializes the timers for the 'submit' and 'resampling' phases
+        of the algorithm run.
+        """
+        self.timer["run"]["submit"] = 0.0
+        self.timer["run"]["resampling"] = 0.0

+
+

+[docs]
+    def _post(self) -> None:
+        """
+        Post-processing after the algorithm execution.
+
+        This method consolidates the results from different temperature steps
+        into single files for 'result' and 'trial'. It also gathers the best
+        results from all processes and writes them to 'best_result.txt'.
+        """
+        for name in ("result", "trial"):
+            with open(self.proc_dir / f"{name}.txt", "w") as fout:
+                self._write_result_header(fout, ["weight", "ancestor"])
+                for Tindex in range(len(self.betas)):
+                    with open(self.proc_dir / f"{name}_T{Tindex}.txt") as fin:
+                        for line in fin:
+                            if line.startswith("#"):
+                                continue
+                            fout.write(line)
+        if self.mpisize > 1:
+            # NOTE:
+            # ``gather`` seems not to work with many processes (say, 32) in some MPI implementation.
+            # ``Gather`` and ``allgather`` seem to work fine.
+            # Since the performance is not so important here, we use ``allgather`` for simplicity.
+            best_fx = self.mpicomm.allgather(self.best_fx)
+            best_x = self.mpicomm.allgather(self.best_x)
+            best_istep = self.mpicomm.allgather(self.best_istep)
+            best_iwalker = self.mpicomm.allgather(self.best_iwalker)
+        else:
+            best_fx = [self.best_fx]
+            best_x = [self.best_x]
+            best_istep = [self.best_istep]
+            best_iwalker = [self.best_iwalker]
+        best_rank = np.argmin(best_fx)
+        if self.mpirank == 0:
+            with open("best_result.txt", "w") as f:
+                f.write(f"nprocs = {self.mpisize}\n")
+                f.write(f"rank = {best_rank}\n")
+                f.write(f"step = {best_istep[best_rank]}\n")
+                f.write(f"walker = {best_iwalker[best_rank]}\n")
+                f.write(f"fx = {best_fx[best_rank]}\n")
+                for label, x in zip(self.label_list, best_x[best_rank]):
+                    f.write(f"{label} = {x}\n")
+            print("Best Result:")
+            print(f"  rank = {best_rank}")
+            print(f"  step = {best_istep[best_rank]}")
+            print(f"  walker = {best_iwalker[best_rank]}")
+            print(f"  fx = {best_fx[best_rank]}")
+            for label, x in zip(self.label_list, best_x[best_rank]):
+                print(f"  {label} = {x}")
+
+            with open("fx.txt", "w") as f:
+                f.write("# $1: 1/T\n")
+                f.write("# $2: mean of f(x)\n")
+                f.write("# $3: standard error of f(x)\n")
+                f.write("# $4: number of replicas\n")
+                f.write("# $5: log(Z/Z0)\n")
+                f.write("# $6: acceptance ratio\n")
+                for i in range(len(self.betas)):
+                    f.write(f"{self.betas[i]}")
+                    f.write(f" {self.Fmeans[i]} {self.Ferrs[i]}")
+                    f.write(f" {self.nreplicas[i]}")
+                    f.write(f" {self.logZs[i]}")
+                    f.write(f" {self.acceptance_ratio[i]}")
+                    f.write("\n")
+        return {
+            "x": best_x[best_rank],
+            "fx": best_fx[best_rank],
+            "nprocs": self.mpisize,
+            "rank": best_rank,
+            "step": best_istep[best_rank],
+            "walker": best_iwalker[best_rank],
+        }

+
+
+

+[docs]
+    def _save_state(self, filename) -> None:
+        """
+        Save the current state of the algorithm to a file.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file where the state will be saved.
+        """
+        data = {
+            #-- _algorithm
+            "mpisize": self.mpisize,
+            "mpirank": self.mpirank,
+            "rng": self.rng.get_state(),
+            "timer": self.timer,
+            "info": self.info,
+            #-- montecarlo
+            "x": self.x,
+            "fx": self.fx,
+            "inode": self.inode,
+            "istep": self.istep,
+            "best_x": self.best_x,
+            "best_fx": self.best_fx,
+            "best_istep": self.best_istep,
+            "best_iwalker": self.best_iwalker,
+            "naccepted": self.naccepted,
+            "ntrial": self.ntrial,
+            #-- pamc
+            "betas": self.betas,
+            "input_as_beta": self.input_as_beta,
+            "numsteps_for_T": self.numsteps_for_T,
+            "Tindex": self.Tindex,
+            "index_from_reset": self.index_from_reset,
+            "logZ": self.logZ,
+            "logZs": self.logZs,
+            "logweights": self.logweights,
+            "Fmeans": self.Fmeans,
+            "Ferrs": self.Ferrs,
+            "nreplicas": self.nreplicas,
+            "populations": self.populations,
+            "family_lo": self.family_lo,
+            "family_hi": self.family_hi,
+            "walker_ancestors": self.walker_ancestors,
+            "fx_from_reset": self.fx_from_reset,
+            "naccepted_from_reset": self.naccepted_from_reset,
+            "acceptance_ratio": self.acceptance_ratio,
+        }
+        self._save_data(data, filename)

+
+
+

+[docs]
+    def _load_state(self, filename, mode="resume", restore_rng=True):
+        """
+        Load the saved state of the algorithm from a file.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file from which the state will be loaded.
+        mode : str, optional
+            The mode in which to load the state. Can be "resume" or "continue", by default "resume".
+        restore_rng : bool, optional
+            Whether to restore the random number generator state, by default True.
+        """
+        data = self._load_data(filename)
+        if not data:
+            print("ERROR: Load status file failed")
+            sys.exit(1)
+
+        #-- _algorithm
+        assert self.mpisize == data["mpisize"]
+        assert self.mpirank == data["mpirank"]
+
+        if restore_rng:
+            self.rng = np.random.RandomState()
+            self.rng.set_state(data["rng"])
+        self.timer = data["timer"]
+
+        info = data["info"]
+        self._check_parameters(info)
+
+        #-- montecarlo
+        self.x = data["x"]
+        self.fx = data["fx"]
+        self.inode = data["inode"]
+
+        self.istep = data["istep"]
+
+        self.best_x = data["best_x"]
+        self.best_fx = data["best_fx"]
+        self.best_istep = data["best_istep"]
+        self.best_iwalker = data["best_iwalker"]
+
+        self.naccepted = data["naccepted"]
+        self.ntrial = data["ntrial"]
+
+        #-- pamc
+        self.Tindex = data["Tindex"]
+        self.index_from_reset = data["index_from_reset"]
+
+        if mode == "resume":
+            # check if scheduling is as stored
+            betas = data["betas"]
+            input_as_beta = data["input_as_beta"]
+            numsteps_for_T = data["numsteps_for_T"]
+
+            assert np.all(betas == self.betas)
+            assert input_as_beta == self.input_as_beta
+            assert np.all(numsteps_for_T == self.numsteps_for_T)
+            assert self.Tindex < len(self.betas)
+
+        elif mode == "continue":
+            # check if scheduling is continuous
+            betas = data["betas"]
+            input_as_beta = data["input_as_beta"]
+            numsteps_for_T = data["numsteps_for_T"]
+
+            assert input_as_beta == self.input_as_beta
+            if not betas[-1] == self.betas[0]:
+                print("ERROR: temperator is not continuous")
+                sys.exit(1)
+            self.betas = np.concatenate([betas, self.betas[1:]])
+            self.numsteps_for_T = np.concatenate([numsteps_for_T, self.numsteps_for_T[1:]])
+
+        else:
+            pass
+
+        numT = len(self.betas)
+
+        nreplicas = self.mpisize * self.nwalkers
+
+        self.logZs = np.zeros(numT)
+        self.Fmeans = np.zeros(numT)
+        self.Ferrs = np.zeros(numT)
+        self.nreplicas = np.full(numT, nreplicas)
+        self.populations = np.zeros((numT, self.nwalkers), dtype=int)
+        self.acceptance_ratio = np.zeros(numT)
+
+        self.logZ = data["logZ"]
+        self.logZs[0:len(data["logZs"])] = data["logZs"]
+        self.logweights = data["logweights"]
+        self.Fmeans[0:len(data["Fmeans"])] = data["Fmeans"]
+        self.Ferrs[0:len(data["Ferrs"])] = data["Ferrs"]
+        self.nreplicas[0:len(data["nreplicas"])] = data["nreplicas"]
+        self.populations[0:len(data["populations"])] = data["populations"]
+
+        self.family_lo = data["family_lo"]
+        self.family_hi = data["family_hi"]
+
+        self.fx_from_reset = data["fx_from_reset"]
+        self.walker_ancestors = data["walker_ancestors"]
+        self.naccepted_from_reset = data["naccepted_from_reset"]
+        self.acceptance_ratio[0:len(data["acceptance_ratio"])] = data["acceptance_ratio"]

+

+
+
+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/domain/_domain.html b/manual/v3.0.0/api/_modules/odatse/domain/_domain.html new file mode 100644 index 00000000..e2d5c988 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/domain/_domain.html @@ -0,0 +1,155 @@ + + + + + + + + odatse.domain._domain — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.domain._domain

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List, Dict, Union, Any
+
+from pathlib import Path
+import numpy as np
+
+import odatse
+
+

+[docs]
+class DomainBase:
+    """
+    Base class for domain management in the 2DMAT software.
+
+    Attributes
+    ----------
+    root_dir : Path
+        The root directory for the domain.
+    output_dir : Path
+        The output directory for the domain.
+    mpisize : int
+        The size of the MPI communicator.
+    mpirank : int
+        The rank of the MPI process.
+    """
+

+[docs]
+    def __init__(self, info: odatse.Info = None):
+        """
+        Initializes the DomainBase instance.
+
+        Parameters
+        ----------
+        info : Info, optional
+            An instance of odatse.Info containing base directory information.
+        """
+        if info:
+            self.root_dir = info.base["root_dir"]
+            self.output_dir = info.base["output_dir"]
+        else:
+            self.root_dir = Path(".")
+            self.output_dir = Path(".")
+
+        self.mpisize = odatse.mpi.size()
+        self.mpirank = odatse.mpi.rank()

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/domain/meshgrid.html b/manual/v3.0.0/api/_modules/odatse/domain/meshgrid.html new file mode 100644 index 00000000..32c098c3 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/domain/meshgrid.html @@ -0,0 +1,340 @@ + + + + + + + + odatse.domain.meshgrid — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.domain.meshgrid

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List, Dict, Union, Any
+
+from pathlib import Path
+import numpy as np
+
+import odatse
+from ._domain import DomainBase
+
+

+[docs]
+class MeshGrid(DomainBase):
+    """
+    MeshGrid class for handling grid data for quantum beam diffraction experiments.
+    """
+
+    grid: List[Union[int, float]] = []
+    grid_local: List[Union[int, float]] = []
+    candicates: int
+
+

+[docs]
+    def __init__(self, info: odatse.Info = None, *, param: Dict[str, Any] = None):
+        """
+        Initialize the MeshGrid object.
+
+        Parameters
+        ----------
+        info : Info, optional
+            Information object containing algorithm parameters.
+        param : dict, optional
+            Dictionary containing parameters for setting up the grid.
+        """
+        super().__init__(info)
+
+        if info:
+            if "param" in info.algorithm:
+                self._setup(info.algorithm["param"])
+            else:
+                raise ValueError("ERROR: algorithm.param not defined")
+        elif param:
+            self._setup(param)
+        else:
+            pass

+
+
+

+[docs]
+    def do_split(self):
+        """
+        Split the grid data among MPI processes.
+        """
+        if self.mpisize > 1:
+            index = [idx for idx, *v in self.grid]
+            index_local = np.array_split(index, self.mpisize)[self.mpirank]
+            self.grid_local = [[idx, *v] for idx, *v in self.grid if idx in index_local]
+        else:
+            self.grid_local = self.grid

+
+
+

+[docs]
+    def _setup(self, info_param):
+        """
+        Setup the grid based on provided parameters.
+
+        Parameters
+        ----------
+        info_param
+            Dictionary containing parameters for setting up the grid.
+        """
+        if "mesh_path" in info_param:
+            self._setup_from_file(info_param)
+        else:
+            self._setup_grid(info_param)
+
+        self.ncandicates = len(self.grid)

+
+
+

+[docs]
+    def _setup_from_file(self, info_param):
+        """
+        Setup the grid from a file.
+
+        Parameters
+        ----------
+        info_param
+            Dictionary containing parameters for setting up the grid.
+        """
+        if "mesh_path" not in info_param:
+            raise ValueError("ERROR: mesh_path not defined")
+        mesh_path = self.root_dir / Path(info_param["mesh_path"]).expanduser()
+
+        if not mesh_path.exists():
+            raise FileNotFoundError("mesh_path not found: {}".format(mesh_path))
+
+        comments = info_param.get("comments", "#")
+        delimiter = info_param.get("delimiter", None)
+        skiprows = info_param.get("skiprows", 0)
+
+        if self.mpirank == 0:
+            data = np.loadtxt(mesh_path, comments=comments, delimiter=delimiter, skiprows=skiprows)
+            if data.ndim == 1:
+                data = data.reshape(1, -1)
+
+            # old format: index x1 x2 ... -> omit index
+            data = data[:, 1:]
+        else:
+            data = None
+
+        if self.mpisize > 1:
+            data = odatse.mpi.comm().bcast(data, root=0)
+
+        self.grid = [[idx, *v] for idx, v in enumerate(data)]

+
+
+

+[docs]
+    def _setup_grid(self, info_param):
+        """
+        Setup the grid based on min, max, and num lists.
+
+        Parameters
+        ----------
+        info_param
+            Dictionary containing parameters for setting up the grid.
+        """
+        if "min_list" not in info_param:
+            raise ValueError("ERROR: algorithm.param.min_list is not defined in the input")
+        min_list = np.array(info_param["min_list"], dtype=float)
+
+        if "max_list" not in info_param:
+            raise ValueError("ERROR: algorithm.param.max_list is not defined in the input")
+        max_list = np.array(info_param["max_list"], dtype=float)
+
+        if "num_list" not in info_param:
+            raise ValueError("ERROR: algorithm.param.num_list is not defined in the input")
+        num_list = np.array(info_param["num_list"], dtype=int)
+
+        if len(min_list) != len(max_list) or len(min_list) != len(num_list):
+            raise ValueError("ERROR: lengths of min_list, max_list, num_list do not match")
+
+        xs = [
+            np.linspace(mn, mx, num=nm)
+            for mn, mx, nm in zip(min_list, max_list, num_list)
+        ]
+
+        self.grid = [
+            [idx, *v] for idx, v in enumerate(
+                np.array(
+                    np.meshgrid(*xs, indexing='xy')
+                ).reshape(len(xs), -1).transpose()
+            )
+        ]

+
+
+

+[docs]
+    def store_file(self, store_path, *, header=""):
+        """
+        Store the grid data to a file.
+
+        Parameters
+        ----------
+        store_path
+            Path to the file where the grid data will be stored.
+        header
+            Header to be included in the file.
+        """
+        if self.mpirank == 0:
+            np.savetxt(store_path, [[*v] for idx, *v in self.grid], header=header)

+
+
+

+[docs]
+    @classmethod
+    def from_file(cls, mesh_path):
+        """
+        Create a MeshGrid object from a file.
+
+        Parameters
+        ----------
+        mesh_path
+            Path to the file containing the grid data.
+
+        Returns
+        -------
+        MeshGrid
+            a MeshGrid object.
+        """
+        return cls(param={"mesh_path": mesh_path})

+
+
+

+[docs]
+    @classmethod
+    def from_dict(cls, param):
+        """
+        Create a MeshGrid object from a dictionary of parameters.
+
+        Parameters
+        ----------
+        param
+            Dictionary containing parameters for setting up the grid.
+
+        Returns
+        -------
+        MeshGrid
+            a MeshGrid object.
+        """
+        return cls(param=param)

+

+
+
+
+if __name__ == "__main__":
+    ms = MeshGrid.from_dict({
+        'min_list': [0,0,0],
+        'max_list': [1,1,1],
+        'num_list': [5,5,5],
+    })
+    ms.store_file("meshfile.dat", header="sample mesh data")
+    
+    ms2 = MeshGrid.from_file("meshfile.dat")
+    ms2.do_split()
+
+    if odatse.mpi.rank() == 0:
+        print(ms2.grid)
+    print(odatse.mpi.rank(), ms2.grid_local)
+
+    ms2.store_file("meshfile2.dat", header="store again")
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/domain/region.html b/manual/v3.0.0/api/_modules/odatse/domain/region.html new file mode 100644 index 00000000..1cf92f2b --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/domain/region.html @@ -0,0 +1,286 @@ + + + + + + + + odatse.domain.region — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.domain.region

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import List, Dict, Union, Any
+
+from pathlib import Path
+import numpy as np
+
+import odatse
+from ._domain import DomainBase
+
+

+[docs]
+class Region(DomainBase):
+    """
+    A class to represent a region in the domain.
+
+    Attributes
+    ----------
+    min_list : np.array
+        Minimum values for each dimension.
+    max_list : np.array
+        Maximum values for each dimension.
+    unit_list : np.array
+        Unit values for each dimension.
+    initial_list : np.array
+        Initial values for each dimension.
+    """
+
+    min_list: np.array
+    max_list: np.array
+    unit_list: np.array
+    initial_list: np.array
+
+

+[docs]
+    def __init__(self, info: odatse.Info = None, *, param: Dict[str, Any] = None):
+        """
+        Initialize the Region object.
+
+        Parameters
+        ----------
+        info : odatse.Info, optional
+            Information object containing algorithm parameters.
+        param : dict, optional
+            Dictionary containing algorithm parameters.
+        """
+        super().__init__(info)
+
+        if info:
+            if "param" in info.algorithm:
+                self._setup(info.algorithm["param"])
+            else:
+                raise ValueError("ERROR: algorithm.param not defined")
+        elif param:
+            self._setup(param)
+        else:
+            pass

+
+
+

+[docs]
+    def _setup(self, info_param):
+        """
+        Setup the region with the given parameters.
+
+        Parameters
+        ----------
+        info_param : dict
+            Dictionary containing the parameters for the region.
+        """
+        if "min_list" not in info_param:
+            raise ValueError("ERROR: algorithm.param.min_list is not defined in the input")
+        min_list = np.array(info_param["min_list"])
+
+        if "max_list" not in info_param:
+            raise ValueError("ERROR: algorithm.param.max_list is not defined in the input")
+        max_list = np.array(info_param["max_list"])
+
+        if len(min_list) != len(max_list):
+            raise ValueError("ERROR: lengths of min_list and max_list do not match")
+
+        self.dimension = len(min_list)
+
+        unit_list = np.array(info_param.get("unit_list", [1.0] * self.dimension))
+
+        self.min_list = min_list
+        self.max_list = max_list
+        self.unit_list = unit_list
+
+        initial_list = np.array(info_param.get("initial_list", []))
+        if initial_list.ndim == 1:
+            initial_list = initial_list.reshape(1, -1)
+
+        if initial_list.size > 0:
+            if initial_list.shape[1] != self.dimension:
+                raise ValueError("ERROR: dimension of initial_list is incorrect")
+            self.num_walkers = initial_list.shape[0]
+        else:
+            self.num_walkers = 0
+
+        self.initial_list = initial_list

+
+
+

+[docs]
+    def initialize(self, rng=np.random, limitation=odatse.util.limitation.Unlimited(), num_walkers: int = 1):
+        """
+        Initialize the region with random values or predefined initial values.
+
+        Parameters
+        ----------
+        rng : numpy.random, optional
+            Random number generator.
+        limitation : odatse.util.limitation, optional
+            Limitation object to judge the validity of the values.
+        num_walkers : int, optional
+            Number of walkers to initialize.
+        """
+        if num_walkers > self.num_walkers:
+            self.num_walkers = num_walkers
+
+        if self.initial_list.size > 0 and self.initial_list.shape[0] >= num_walkers:
+            pass
+        else:
+            self._init_random(rng=rng, limitation=limitation)

+
+
+

+[docs]
+    def _init_random(self, rng=np.random, limitation=odatse.util.limitation.Unlimited(), max_count=100):
+        """
+        Initialize the region with random values within the specified limits.
+
+        Parameters
+        ----------
+        rng : numpy.random, optional
+            Random number generator.
+        limitation : odatse.util.limitation, optional
+            Limitation object to judge the validity of the values.
+        max_count : int, optional
+            Maximum number of trials to generate valid values.
+        """
+        initial_list = np.zeros((self.num_walkers, self.dimension), dtype=float)
+        is_ok = np.full(self.num_walkers, False)
+
+        if self.initial_list.size > 0:
+            nitem = min(self.num_walkers, self.initial_list.shape[0])
+            initial_list[0:nitem] = self.initial_list[0:nitem]
+            is_ok[0:nitem] = True
+
+        count = 0
+        while (not np.all(is_ok)):
+            count += 1
+            initial_list[~is_ok] = self.min_list + (self.max_list - self.min_list) * rng.rand(np.count_nonzero(~is_ok), self.dimension)
+            is_ok = np.array([limitation.judge(v) for v in initial_list])
+            if count >= max_count:
+                raise RuntimeError("ERROR: init_random: trial count exceeds {}".format(max_count))
+        self.initial_list = initial_list

+

+
+
+if __name__ == "__main__":
+    reg = Region(param={
+        "min_list": [0.0, 0.0, 0.0],
+        "max_list": [1.0, 1.0, 1.0],
+        "initial_list": [[0.1, 0.2, 0.3],
+                         [0.2, 0.3, 0.1],
+                         [0.3, 0.1, 0.2],
+                         [0.2, 0.1, 0.3],
+                         [0.1, 0.3, 0.2],
+                         ],
+    })
+
+    #lim = odatse.util.limitation.Unlimited()
+    lim = odatse.util.limitation.Inequality(a=np.array([[1,0,0],[-1,-1,-1]]),b=np.array([0,1]),is_limitary=True)
+    
+    reg.initialize(np.random, lim, 8)
+    
+    print(reg.min_list, reg.max_list, reg.unit_list, reg.initial_list, reg.num_walkers)
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/exception.html b/manual/v3.0.0/api/_modules/odatse/exception.html new file mode 100644 index 00000000..1f77a00e --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/exception.html @@ -0,0 +1,133 @@ + + + + + + + + odatse.exception — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.exception

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+

+[docs]
+class Error(Exception):
+    """Base class of exceptions in odatse"""
+
+    pass

+
+
+
+

+[docs]
+class InputError(Error):
+    """
+    Exception raised for errors in inputs
+
+    Parameters
+    ----------
+    message : str
+        explanation
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message = message

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/solver/_solver.html b/manual/v3.0.0/api/_modules/odatse/solver/_solver.html new file mode 100644 index 00000000..a8aa219d --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/solver/_solver.html @@ -0,0 +1,199 @@ + + + + + + + + odatse.solver._solver — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.solver._solver

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from abc import ABCMeta, abstractmethod
+
+import subprocess
+import numpy as np
+
+import odatse
+import odatse.mpi
+
+# type hints
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+

+[docs]
+class SolverBase(object, metaclass=ABCMeta):
+    """
+    Abstract base class for solvers in the 2DMAT software.
+    """
+
+    root_dir: Path
+    output_dir: Path
+    proc_dir: Path
+    work_dir: Path
+    _name: str
+    dimension: int
+    timer: Dict[str, Dict]
+
+

+[docs]
+    @abstractmethod
+    def __init__(self, info: odatse.Info) -> None:
+        """
+        Initialize the solver with the given information.
+
+        Parameters
+        ----------
+        info : Info
+            Information object containing configuration details.
+        """
+        self.root_dir = info.base["root_dir"]
+        self.output_dir = info.base["output_dir"]
+        self.proc_dir = self.output_dir / str(odatse.mpi.rank())
+        self.work_dir = self.proc_dir
+        self._name = ""
+        self.timer = {"prepare": {}, "run": {}, "post": {}}
+        if "dimension" in info.solver:
+            self.dimension = info.solver["dimension"]
+        else:
+            self.dimension = info.base["dimension"]

+
+
+    @property
+    def name(self) -> str:
+        """
+        Get the name of the solver.
+
+        Returns
+        -------
+        str
+            The name of the solver.
+        """
+        return self._name
+
+

+[docs]
+    @abstractmethod
+    def evaluate(self, x: np.ndarray, arg: Tuple = (), nprocs: int = 1, nthreads: int = 1) -> None:
+        """
+        Evaluate the solver with the given parameters.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input data array.
+        arg : Tuple, optional
+            Additional arguments for evaluation. Defaults to ().
+        nprocs : nt, optional
+            Number of processes to use. Defaults to 1.
+        nthreads : int, optional
+            Number of threads to use. Defaults to 1.
+
+        Raises
+        ------
+        NotImplementedError
+            This method should be implemented by subclasses.
+        """
+        raise NotImplementedError()

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/solver/analytical.html b/manual/v3.0.0/api/_modules/odatse/solver/analytical.html new file mode 100644 index 00000000..f4ab024c --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/solver/analytical.html @@ -0,0 +1,330 @@ + + + + + + + + odatse.solver.analytical — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.solver.analytical

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import numpy as np
+
+import odatse
+import odatse.solver.function
+
+

+[docs]
+def quadratics(xs: np.ndarray) -> float:
+    """
+    Quadratic (sphere) function.
+
+    Parameters
+    ----------
+    xs : np.ndarray
+        Input array.
+
+    Returns
+    -------
+    float
+        The calculated value of the quadratic function.
+
+    Notes
+    -----
+    It has one global minimum f(xs)=0 at xs = [0,0,...,0].
+    """
+    return np.sum(xs * xs)

+
+
+

+[docs]
+def quartics(xs: np.ndarray) -> float:
+    """
+    Quartic function with two global minima.
+
+    Parameters
+    ----------
+    xs : np.ndarray
+        Input array.
+
+    Returns
+    -------
+    float
+        The calculated value of the quartic function.
+
+    Notes
+    -----
+    It has two global minima f(xs)=0 at xs = [1,1,...,1] and [0,0,...,0].
+    It has one saddle point f(0,0,...,0) = 1.0.
+    """
+    return np.mean((xs - 1.0) ** 2) * np.mean((xs + 1.0) ** 2)

+
+
+
+

+[docs]
+def ackley(xs: np.ndarray) -> float:
+    """
+    Ackley's function in arbitrary dimension
+
+    Parameters
+    ----------
+    xs : np.ndarray
+        Input array.
+
+    Returns
+    -------
+    float
+        The calculated value of Ackley's function.
+
+    Notes
+    -----
+    It has one global minimum f(xs)=0 at xs=[0,0,...,0].
+    It has many local minima.
+    """
+    a = np.mean(xs ** 2)
+    a = 20 * np.exp(-0.2 * np.sqrt(a))
+    b = np.cos(2.0 * np.pi * xs)
+    b = np.exp(0.5 * np.sum(b))
+    return 20.0 + np.exp(1.0) - a - b

+
+
+

+[docs]
+def rosenbrock(xs: np.ndarray) -> float:
+    """
+    Rosenbrock's function.
+
+    Parameters
+    ----------
+    xs : np.ndarray
+        Input array.
+
+    Returns
+    -------
+    float
+        The calculated value of Rosenbrock's function.
+
+    Notes
+    -----
+    It has one global minimum f(xs) = 0 at xs=[1,1,...,1].
+    """
+    return np.sum(100.0 * (xs[1:] - xs[:-1] ** 2) ** 2 + (1.0 - xs[:-1]) ** 2)

+
+
+

+[docs]
+def himmelblau(xs: np.ndarray) -> float:
+    """
+    Himmelblau's function.
+
+    Parameters
+    ----------
+    xs : np.ndarray
+        Input array of shape (2,).
+
+    Returns
+    -------
+    float
+        The calculated value of Himmelblau's function.
+
+    Notes
+    -----
+    It has four global minima f(xs) = 0 at
+    xs=[3,2], [-2.805118..., 3.131312...], [-3.779310..., -3.2831860], and [3.584428..., -1.848126...].
+    """
+    if xs.shape[0] != 2:
+        raise RuntimeError(
+            f"ERROR: himmelblau expects d=2 input, but receives d={xs.shape[0]} one"
+        )
+    return (xs[0] ** 2 + xs[1] - 11.0) ** 2 + (xs[0] + xs[1] ** 2 - 7.0) ** 2

+
+
+

+[docs]
+def linear_regression_test(xs: np.ndarray) -> float:
+    """
+    Negative log likelihood of linear regression with Gaussian noise N(0,sigma)
+
+    y = ax + b
+
+    trained by xdata = [1, 2, 3, 4, 5, 6] and ydata = [1, 3, 2, 4, 3, 5].
+
+    Model parameters (a, b, sigma) are corresponding to xs as the following,
+    a = xs[0], b = xs[1], log(sigma**2) = xs[2]
+
+    It has a global minimum f(xs) = 1.005071.. at
+    xs = [0.628571..., 0.8, -0.664976...].
+
+    Parameters
+    ----------
+    xs : np.ndarray
+        Input array of model parameters.
+
+    Returns
+    -------
+    float
+        The negative log likelihood of the linear regression model.
+    """
+    if xs.shape[0] != 3:
+        raise RuntimeError(
+            f"ERROR: regression expects d=3 input, but receives d={xs.shape[0]} one"
+        )
+
+    xdata = np.array([1, 2, 3, 4, 5, 6])
+    ydata = np.array([1, 3, 2, 4, 3, 5])
+    n = len(ydata)
+
+    return 0.5 * (
+        n * xs[2] + np.sum((xs[0] * xdata + xs[1] - ydata) ** 2) / np.exp(xs[2])
+    )

+
+
+

+[docs]
+class Solver(odatse.solver.function.Solver):
+    """Function Solver with pre-defined benchmark functions"""
+
+    x: np.ndarray
+    fx: float
+
+

+[docs]
+    def __init__(self, info: odatse.Info) -> None:
+        """
+        Initialize the solver.
+
+        Parameters
+        ----------
+        info: Info
+            Information object containing solver configuration.
+        """
+        super().__init__(info)
+        self._name = "analytical"
+        function_name = info.solver.get("function_name", "quadratics")
+
+        if function_name == "quadratics":
+            self.set_function(quadratics)
+        elif function_name == "quartics":
+            self.set_function(quartics)
+        elif function_name == "ackley":
+            self.set_function(ackley)
+        elif function_name == "rosenbrock":
+            self.set_function(rosenbrock)
+        elif function_name == "himmelblau":
+            dimension = self.dimension
+            if int(dimension) != 2:
+                raise RuntimeError(
+                    f"ERROR: himmelblau works only with dimension=2 but input is dimension={dimension}"
+                )
+            self.set_function(himmelblau)
+        elif function_name == "linear_regression_test":
+            dimension = self.dimension
+            if int(dimension) != 3:
+                raise RuntimeError(
+                    f"ERROR: regression works only with dimension=2 but input is dimension={dimension}"
+                )
+            self.set_function(linear_regression_test)
+        else:
+            raise RuntimeError(f"ERROR: Unknown function, {function_name}")

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/solver/function.html b/manual/v3.0.0/api/_modules/odatse/solver/function.html new file mode 100644 index 00000000..18d6d808 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/solver/function.html @@ -0,0 +1,251 @@ + + + + + + + + odatse.solver.function — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.solver.function

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import os
+import numpy as np
+import odatse
+import time
+
+# type hints
+from pathlib import Path
+from typing import Callable, Optional, Dict, Tuple
+
+
+

+[docs]
+class Solver(odatse.solver.SolverBase):
+    """
+    Solver class for evaluating functions with given parameters.
+    """
+    x: np.ndarray
+    fx: float
+    _func: Optional[Callable[[np.ndarray], float]]
+
+

+[docs]
+    def __init__(self, info: odatse.Info) -> None:
+        """
+        Initialize the solver.
+
+        Parameters
+        ----------
+        info: Info
+            Information object containing solver configuration.
+        """
+        super().__init__(info)
+        self._name = "function"
+        self._func = None
+
+        # for debug purpose
+        self.delay = info.solver.get("delay", 0.0)

+
+
+

+[docs]
+    def evaluate(self, x: np.ndarray, args: Tuple = (), nprocs: int = 1, nthreads: int = 1) -> float:
+        """
+        Evaluate the function with given parameters.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array for the function.
+        args : Tuple, optional
+            Additional arguments for the function.
+        nprocs : int, optional
+            Number of processes to use.
+        nthreads : int, optional
+            Number of threads to use.
+
+        Returns
+        -------
+        float
+            Result of the function evaluation.
+        """
+        self.prepare(x, args)
+        cwd = os.getcwd()
+        os.chdir(self.work_dir)
+        self.run(nprocs, nthreads)
+        os.chdir(cwd)
+        result = self.get_results()
+        return result

+
+
+

+[docs]
+    def prepare(self, x: np.ndarray, args = ()) -> None:
+        """
+        Prepare the solver with the given parameters.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array for the function.
+        args : tuple, optional
+            Additional arguments for the function.
+        """
+        self.x = x

+
+
+

+[docs]
+    def run(self, nprocs: int = 1, nthreads: int = 1) -> None:
+        """
+        Run the function evaluation.
+
+        Parameters
+        ----------
+        nprocs : int, optional
+            Number of processes to use.
+        nthreads : int, optional
+            Number of threads to use.
+
+        Raises
+        ------
+        RuntimeError
+            If the function is not set.
+        """
+        if self._func is None:
+            raise RuntimeError(
+                "ERROR: function is not set. Make sure that `set_function` is called."
+            )
+        self.fx = self._func(self.x)
+        # for debug purpose
+        if self.delay > 0.0:
+            time.sleep(self.delay)

+
+
+

+[docs]
+    def get_results(self) -> float:
+        """
+        Get the results of the function evaluation.
+
+        Returns
+        -------
+        float
+            Result of the function evaluation.
+        """
+        return self.fx

+
+
+

+[docs]
+    def set_function(self, f: Callable[[np.ndarray], float]) -> None:
+        """
+        Set the function to be evaluated.
+
+        Parameters
+        ----------
+        f : Callable[[np.ndarray], float]
+            Function to be evaluated.
+        """
+        self._func = f

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/graph.html b/manual/v3.0.0/api/_modules/odatse/util/graph.html new file mode 100644 index 00000000..971e6334 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/graph.html @@ -0,0 +1,180 @@ + + + + + + + + odatse.util.graph — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.graph

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+
+from typing import List
+
+import collections
+import numpy as np
+
+
+

+[docs]
+def is_connected(nnlist: List[List[int]]) -> bool:
+    """
+    Check if the graph represented by the neighbor list is connected.
+
+    Parameters
+    ----------
+    nnlist : List[List[int]]
+        A list of lists where each sublist represents the neighbors of a node.
+
+    Returns
+    -------
+    bool
+        True if the graph is connected, False otherwise.
+    """
+    nnodes = len(nnlist)
+    visited = np.full(nnodes, False)
+    nvisited = 1
+    visited[0] = True
+    stack = collections.deque([0])
+    while len(stack) > 0:
+        node = stack.pop()
+        neighbors = [n for n in nnlist[node] if not visited[n]]
+        visited[neighbors] = True
+        stack.extend(neighbors)
+        nvisited += len(neighbors)
+
+    return nvisited == nnodes

+
+
+
+

+[docs]
+def is_bidirectional(nnlist: List[List[int]]) -> bool:
+    """
+    Check if the graph represented by the neighbor list is bidirectional.
+
+    Parameters
+    ----------
+    nnlist : List[List[int]]
+        A list of lists where each sublist represents the neighbors of a node.
+
+    Returns
+    -------
+    bool
+        True if the graph is bidirectional, False otherwise.
+    """
+    for i in range(len(nnlist)):
+        for j in nnlist[i]:
+            if i not in nnlist[j]:
+                return False
+    return True

+
+
+if __name__ == "__main__":
+    filename = "./neighborlist.txt"
+    nnlist = []
+    with open(filename) as f:
+        for line in f:
+            words = line.split()
+            nn = [int(w) for w in words[1:]]
+            nnlist.append(nn)
+    print(is_connected(nnlist))
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/limitation.html b/manual/v3.0.0/api/_modules/odatse/util/limitation.html new file mode 100644 index 00000000..3a1986e7 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/limitation.html @@ -0,0 +1,297 @@ + + + + + + + + odatse.util.limitation — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.limitation

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from abc import ABCMeta, abstractmethod
+
+import numpy as np
+
+from .read_matrix import read_matrix, read_vector
+
+
+

+[docs]
+class LimitationBase(metaclass=ABCMeta):
+    """
+    Abstract base class for limitations.
+    """
+
+

+[docs]
+    @abstractmethod
+    def __init__(self, is_limitary: bool):
+        """
+        Initialize the limitation.
+
+        Parameters
+        ----------
+        is_limitary : bool
+            Boolean indicating if the limitation is active.
+        """
+        self.is_limitary = is_limitary

+
+
+

+[docs]
+    @abstractmethod
+    def judge(self, x: np.ndarray) -> bool:
+        """
+        Abstract method to judge if the limitation is satisfied.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array to be judged.
+
+        Returns
+        -------
+        bool
+            Boolean indicating if the limitation is satisfied.
+        """
+        raise NotImplementedError

+

+
+
+

+[docs]
+class Unlimited(LimitationBase):
+    """
+    Class representing an unlimited (no limitation) condition.
+    """
+
+

+[docs]
+    def __init__(self):
+        """
+        Initialize the unlimited condition.
+        """
+        super().__init__(False)

+
+
+

+[docs]
+    def judge(self, x: np.ndarray) -> bool:
+        """
+        Always returns True as there is no limitation.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array to be judged.
+
+        Returns
+        -------
+        bool
+            Always True.
+        """
+        return True

+

+
+
+

+[docs]
+class Inequality(LimitationBase):
+    """
+    Class representing an inequality limitation.
+    """
+
+

+[docs]
+    def __init__(self, a: np.ndarray, b: np.ndarray, is_limitary: bool):
+        """
+        Initialize the inequality limitation.
+
+        Parameters
+        ----------
+        a : np.ndarray
+            Coefficient matrix.
+        b : np.ndarray
+            Constant vector.
+        is_limitary : bool
+            Boolean indicating if the limitation is active.
+        """
+        super().__init__(is_limitary)
+        if self.is_limitary:
+            self.a = np.array(a)
+            self.b = np.array(b)
+            self.minusb = -np.array(b)
+            self.n_formula = a.shape[0]
+            self.ndim = a.shape[1]

+
+
+

+[docs]
+    def judge(self, x: np.ndarray) -> bool:
+        """
+        Judge if the inequality limitation is satisfied.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array to be judged.
+
+        Returns
+        -------
+        bool
+            Boolean indicating if the limitation is satisfied.
+        """
+        if self.is_limitary:
+            Ax_b = np.dot(self.a, x) + self.b
+            judge_result = np.all(Ax_b > 0)
+        else:
+            judge_result = True
+        return judge_result

+
+
+

+[docs]
+    @classmethod
+    def from_dict(cls, d):
+        """
+        Create an Inequality instance from a dictionary.
+
+        Parameters
+        ----------
+        d
+            Dictionary containing 'co_a' and 'co_b' keys.
+
+        Returns
+        -------
+        Inequality
+            an Inequality instance.
+        """
+        co_a: np.ndarray = read_matrix(d.get("co_a", []))
+        co_b: np.ndarray = read_matrix(d.get("co_b", []))
+
+        if co_a.size == 0:
+            is_set_co_a = False
+        else:
+            if co_a.ndim == 2:
+                is_set_co_a = True
+            else:
+                raise ValueError("co_a should be a matrix of size equal to number of constraints times dimension")
+
+        if co_b.size == 0:
+            is_set_co_b = False
+        else:
+            if co_b.ndim == 2 and co_b.shape == (co_a.shape[0], 1):
+                is_set_co_b = True
+            else:
+                raise ValueError("co_b should be a column vector of size equal to number of constraints")
+
+        if is_set_co_a and is_set_co_b:
+            is_limitary = True
+        elif (not is_set_co_a) and (not is_set_co_b):
+            is_limitary = False
+        else:
+            msg = "ERROR: Both co_a and co_b must be defined."
+            raise ValueError(msg)
+
+        return cls(co_a, co_b.reshape(-1), is_limitary)

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/logger.html b/manual/v3.0.0/api/_modules/odatse/util/logger.html new file mode 100644 index 00000000..6d6295ee --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/logger.html @@ -0,0 +1,283 @@ + + + + + + + + odatse.util.logger — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.logger

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import time
+import odatse
+import numpy as np
+
+# type hints
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+# Parameters
+# ----------
+# [runner.log]
+#   interval
+#   filename
+#   write_input
+#   write_result
+
+

+[docs]
+class Logger:
+    """
+    Logger class to handle logging of calls, elapsed time, and optionally input and result data.
+    """
+
+    logfile: Path
+    buffer_size: int
+    buffer: List[str]
+    num_calls: int
+    time_start: float
+    time_previous: float
+    to_write_result: bool
+    to_write_input: bool
+
+

+[docs]
+    def __init__(self, info: Optional[odatse.Info] = None,
+                 *,
+                 buffer_size: int = 0,
+                 filename: str = "runner.log",
+                 write_input: bool = False,
+                 write_result: bool = False,
+                 params: Optional[Dict[str,Any]] = None,
+                 **rest) -> None:
+        """
+        Initialize the Logger.
+
+        Parameters
+        ----------
+        info : Info, optional
+            Information object containing logging parameters.
+        buffer_size : int
+            Size of the buffer before writing to the log file.
+        filename : str
+            Name of the log file.
+        write_input : bool
+            Flag to indicate if input should be logged.
+        write_result : bool
+            Flag to indicate if result should be logged.
+        params : Dict[str,Any]], optional
+            Additional parameters for logging.
+        **rest
+            Additional keyword arguments.
+        """
+        if info is not None:
+            info_log = info.runner.get("log", {})
+        else:
+            info_log = params
+
+        self.buffer_size = info_log.get("interval", buffer_size)
+        self.filename = info_log.get("filename", filename)
+        self.to_write_input = info_log.get("write_input", write_input)
+        self.to_write_result = info_log.get("write_result", write_result)
+
+        self.time_start = time.perf_counter()
+        self.time_previous = self.time_start
+        self.num_calls = 0
+        self.buffer = []

+
+
+

+[docs]
+    def is_active(self) -> bool:
+        """
+        Check if logging is active.
+
+        Returns
+        -------
+        bool
+            True if logging is active, False otherwise.
+        """
+        return self.buffer_size > 0

+
+
+

+[docs]
+    def prepare(self, proc_dir: Path) -> None:
+        """
+        Prepare the log file for writing.
+
+        Parameters
+        ----------
+        proc_dir : Path
+            Directory where the log file will be created.
+        """
+        if not self.is_active():
+            return
+
+        self.logfile = proc_dir / self.filename
+        if self.logfile.exists():
+            self.logfile.unlink()
+
+        with open(self.logfile, "w") as f:
+            f.write("# $1: num_calls\n")
+            f.write("# $2: elapsed time from last call\n")
+            f.write("# $3: elapsed time from start\n")
+            if self.to_write_result:
+                f.write("# $4: result\n")
+            if self.to_write_input:
+                f.write("# ${}-: input\n".format(5 if self.to_write_result else 4))
+            f.write("\n")

+
+
+

+[docs]
+    def count(self, x: np.ndarray, args, result: float) -> None:
+        """
+        Log a call with input and result data.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input data.
+        args :
+            Additional arguments.
+        result : float
+            Result data.
+        """
+        if not self.is_active():
+            return
+
+        self.num_calls += 1
+
+        t = time.perf_counter()
+
+        fields = []
+        fields.append(str(self.num_calls).ljust(6))
+        fields.append("{:.6f}".format(t - self.time_previous))
+        fields.append("{:.6f}".format(t - self.time_start))
+        if self.to_write_result:
+            fields.append(result)
+        if self.to_write_input:
+            for val in x:
+                fields.append(val)
+        self.buffer.append(" ".join(map(str, fields)) + "\n")
+
+        self.time_previous = t
+
+        if len(self.buffer) >= self.buffer_size:
+            self.write()

+
+
+

+[docs]
+    def write(self) -> None:
+        """
+        Write the buffered log entries to the log file.
+        """
+        if not self.is_active():
+            return
+        with open(self.logfile, "a") as f:
+            for w in self.buffer:
+                f.write(w)
+        self.buffer.clear()

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/mapping.html b/manual/v3.0.0/api/_modules/odatse/util/mapping.html new file mode 100644 index 00000000..7d16a64c --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/mapping.html @@ -0,0 +1,277 @@ + + + + + + + + odatse.util.mapping — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.mapping

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import copy
+import numpy as np
+
+from .read_matrix import read_matrix
+
+# type hints
+from typing import Optional
+
+

+[docs]
+class MappingBase:
+    """
+    Base class for mapping operations.
+    """
+
+    def __init__(self):
+        pass
+
+    def __call__(self, x: np.ndarray) -> np.ndarray:
+        """
+        Apply the mapping to the input array.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array.
+
+        Returns
+        -------
+        np.ndarray
+            Mapped array.
+        """
+        raise NotImplementedError

+
+
+
+

+[docs]
+class TrivialMapping(MappingBase):
+    """
+    A trivial mapping that returns the input array unchanged.
+    """
+
+    def __init__(self):
+        super().__init__()
+
+    def __call__(self, x: np.ndarray) -> np.ndarray:
+        """
+        Return the input array unchanged.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array.
+
+        Returns
+        -------
+        np.ndarray
+            The same input array.
+        """
+        return x

+
+
+
+

+[docs]
+class Affine(MappingBase):
+    """
+    An affine mapping defined by a matrix A and a vector b.
+    """
+
+    A: Optional[np.ndarray]
+    b: Optional[np.ndarray]
+
+

+[docs]
+    def __init__(self, A: Optional[np.ndarray] = None, b: Optional[np.ndarray] = None):
+        """
+        Initialize the affine mapping.
+
+        Parameters
+        ----------
+        A : np.ndarray, optional
+            Transformation matrix.
+        b : np.ndarray, optional
+            Translation vector.
+        """
+        # copy arguments
+        self.A = np.array(A) if A is not None else None
+        self.b = np.array(b) if b is not None else None
+
+        # check
+        if self.A is not None:
+            if not self.A.ndim == 2:
+                raise ValueError("A is not a matrix")
+        if self.b is not None:
+            if not self.b.ndim == 1:
+                raise ValueError("b is not a vector")
+        if self.A is not None and self.b is not None:
+            if not self.A.shape[0] == self.b.shape[0]:
+                raise ValueError("shape of A and b mismatch")

+
+
+    def __call__(self, x: np.ndarray) -> np.ndarray:
+        """
+        Apply the affine mapping to the input array.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            Input array.
+
+        Returns
+        -------
+        np.ndarray
+            Mapped array.
+        """
+        if self.A is None:
+            ret = copy.copy(x)
+        else:
+            ret = np.dot(self.A, x)
+        if self.b is None:
+            return ret
+        else:
+            return ret + self.b
+
+

+[docs]
+    @classmethod
+    def from_dict(cls, d):
+        """
+        Create an Affine instance from a dictionary.
+
+        Parameters
+        ----------
+        d : dict
+            Dictionary containing 'A' and 'b' keys.
+
+        Returns
+        -------
+        Affine
+            An instance of the Affine class.
+        """
+        A: Optional[np.ndarray] = read_matrix(d.get("A", []))
+        b: Optional[np.ndarray] = read_matrix(d.get("b", []))
+
+        if A is None:
+            pass
+        elif A.size == 0:
+            A = None
+        else:
+            if not A.ndim == 2:
+                raise ValueError("A should be a matrix")
+
+        if b is None:
+            pass
+        elif b.size == 0:
+            b = None
+        else:
+            if not (b.ndim == 2 and b.shape[1] == 1):
+                raise ValueError("b should be a column vector")
+            if not (A is not None and b.shape[0] == A.shape[0]):
+                raise ValueError("shape of A and b mismatch")
+            b = b.reshape(-1)
+
+        return cls(A, b)

+

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/neighborlist.html b/manual/v3.0.0/api/_modules/odatse/util/neighborlist.html new file mode 100644 index 00000000..50e6db56 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/neighborlist.html @@ -0,0 +1,654 @@ + + + + + + + + odatse.util.neighborlist — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.neighborlist

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import typing
+from typing import List, Set
+from os import PathLike
+
+import sys
+import itertools
+
+import numpy as np
+
+from odatse import mpi
+
+try:
+    from tqdm import tqdm
+
+    has_tqdm = True
+except:
+    has_tqdm = False
+
+
+

+[docs]
+class Cells:
+    """
+    A class to represent a grid of cells for spatial partitioning.
+    """
+
+    cells: List[Set[int]]
+    dimension: int
+    mins: np.ndarray
+    maxs: np.ndarray
+    Ns: np.ndarray
+    ncell: int
+    cellsize: float
+
+

+[docs]
+    def __init__(self, mins: np.ndarray, maxs: np.ndarray, cellsize: float):
+        """
+        Initialize the Cells object.
+
+        Parameters
+        ----------
+        mins : np.ndarray
+            The minimum coordinates of the grid.
+        maxs : np.ndarray
+            The maximum coordinates of the grid.
+        cellsize : float
+            The size of each cell.
+        """
+        self.dimension = len(mins)
+        self.mins = mins
+        Ls = (maxs - mins) * 1.001
+        self.Ns = np.ceil(Ls / cellsize).astype(np.int64)
+        self.maxs = self.mins + cellsize * self.Ns
+        self.cellsize = cellsize
+        self.ncell = typing.cast(int, np.prod(self.Ns))
+        self.cells = [set() for _ in range(self.ncell)]

+
+
+

+[docs]
+    def coord2cellindex(self, x: np.ndarray) -> int:
+        """
+        Convert coordinates to a cell index.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The coordinates to convert.
+
+        Returns
+        -------
+        int
+            The index of the cell.
+        """
+        return self.cellcoord2cellindex(self.coord2cellcoord(x))

+
+
+

+[docs]
+    def coord2cellcoord(self, x: np.ndarray) -> np.ndarray:
+        """
+        Convert coordinates to cell coordinates.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The coordinates to convert.
+
+        Returns
+        -------
+        np.ndarray
+            The cell coordinates.
+        """
+        return np.floor((x - self.mins) / self.cellsize).astype(np.int64)

+
+
+

+[docs]
+    def cellcoord2cellindex(self, ns: np.ndarray) -> int:
+        """
+        Convert cell coordinates to a cell index.
+
+        Parameters
+        ----------
+        ns : np.ndarray
+            The cell coordinates to convert.
+
+        Returns
+        -------
+        int
+            The index of the cell.
+        """
+        index = 0
+        oldN = 1
+        for n, N in zip(ns, self.Ns):
+            index *= oldN
+            index += n
+            oldN = N
+        return index

+
+
+

+[docs]
+    def cellindex2cellcoord(self, index: int) -> np.ndarray:
+        """
+        Convert a cell index to cell coordinates.
+
+        Parameters
+        ----------
+        index : int
+            The index of the cell.
+
+        Returns
+        -------
+        np.ndarray
+            The cell coordinates.
+        """
+        ns = np.zeros(self.dimension, dtype=np.int64)
+        for d in range(self.dimension):
+            d = self.dimension - d - 1
+            N = self.Ns[d]
+            ns[d] = index % N
+            index = index // N
+        return ns

+
+
+

+[docs]
+    def out_of_bound(self, ns: np.ndarray) -> bool:
+        """
+        Check if cell coordinates are out of bounds.
+
+        Parameters
+        ----------
+        ns : np.ndarray
+            The cell coordinates to check.
+
+        Returns
+        -------
+        bool
+            True if out of bounds, False otherwise.
+        """
+        if np.any(ns < 0):
+            return True
+        if np.any(ns >= self.Ns):
+            return True
+        return False

+
+
+

+[docs]
+    def neighborcells(self, index: int) -> List[int]:
+        """
+        Get the indices of neighboring cells.
+
+        Parameters
+        ----------
+        index : int
+            The index of the cell.
+
+        Returns
+        -------
+        List[int]
+            The indices of the neighboring cells.
+        """
+        neighbors: List[int] = []
+        center_coord = self.cellindex2cellcoord(index)
+        for diff in itertools.product([-1, 0, 1], repeat=self.dimension):
+            other_coord = center_coord + np.array(diff)
+            if self.out_of_bound(other_coord):
+                continue
+            other_coord_index = self.cellcoord2cellindex(other_coord)
+            neighbors.append(other_coord_index)
+        return neighbors

+

+
+
+

+[docs]
+def make_neighbor_list_cell(
+    X: np.ndarray,
+    radius: float,
+    allow_selfloop: bool,
+    show_progress: bool,
+    comm: mpi.Comm = None,
+) -> List[List[int]]:
+    """
+    Create a neighbor list using cell-based spatial partitioning.
+
+    Parameters
+    ----------
+    X : np.ndarray
+        The coordinates of the points.
+    radius : float
+        The radius within which neighbors are considered.
+    allow_selfloop : bool
+        Whether to allow self-loops in the neighbor list.
+    show_progress : bool
+        Whether to show a progress bar.
+    comm : mpi.Comm, optional
+        The MPI communicator.
+
+    Returns
+    -------
+    List[List[int]]
+        The neighbor list.
+    """
+    if comm is None:
+        mpisize = 1
+        mpirank = 0
+    else:
+        mpisize = comm.size
+        mpirank = comm.rank
+
+    mins = typing.cast(np.ndarray, X.min(axis=0))
+    maxs = typing.cast(np.ndarray, X.max(axis=0))
+    cells = Cells(mins, maxs, radius * 1.001)
+    npoints = X.shape[0]
+    for n in range(npoints):
+        xs = X[n, :]
+        index = cells.coord2cellindex(xs)
+        cells.cells[index].add(n)
+
+    points = np.array_split(range(npoints), mpisize)[mpirank]
+    npoints_local = len(points)
+    nnlist: List[List[int]] = [[] for _ in range(npoints_local)]
+    if show_progress and mpirank == 0:
+        if has_tqdm:
+            desc = "rank 0" if mpisize > 1 else None
+            ns = tqdm(points, desc=desc)
+        else:
+            print("WARNING: cannot show progress because tqdm package is not available")
+            ns = points
+    else:
+        ns = points
+    for n in ns:
+        xs = X[n, :]
+        cellindex = cells.coord2cellindex(xs)
+        for neighborcell in cells.neighborcells(cellindex):
+            for other in cells.cells[neighborcell]:
+                if (not allow_selfloop) and n == other:
+                    continue
+                ys = X[other, :]
+                r = np.linalg.norm(xs - ys)
+                if r <= radius:
+                    nnlist[n - points[0]].append(other)
+    if mpisize > 1:
+        nnlist = list(itertools.chain.from_iterable(comm.allgather(nnlist)))
+    return nnlist

+
+
+
+

+[docs]
+def make_neighbor_list_naive(
+    X: np.ndarray,
+    radius: float,
+    allow_selfloop: bool,
+    show_progress: bool,
+    comm: mpi.Comm = None,
+) -> List[List[int]]:
+    """
+    Create a neighbor list using a naive all-pairs approach.
+
+    Parameters
+    ----------
+    X : np.ndarray)
+        The coordinates of the points.
+    radius : float
+        The radius within which neighbors are considered.
+    allow_selfloop : bool
+        Whether to allow self-loops in the neighbor list.
+    show_progress : bool
+        Whether to show a progress bar.
+    comm : mpi.Comm, optional
+        The MPI communicator.
+
+    Returns
+    -------
+    List[List[int]]
+        The neighbor list.
+    """
+    if comm is None:
+        mpisize = 1
+        mpirank = 0
+    else:
+        mpisize = comm.size
+        mpirank = comm.rank
+
+    npoints = X.shape[0]
+    points = np.array_split(range(npoints), mpisize)[mpirank]
+    npoints_local = len(points)
+    nnlist: List[List[int]] = [[] for _ in range(npoints_local)]
+    if show_progress and mpirank == 0:
+        if has_tqdm:
+            desc = "rank 0" if mpisize > 1 else None
+            ns = tqdm(points, desc=desc)
+        else:
+            print("WARNING: cannot show progress because tqdm package is not available")
+            ns = points
+    else:
+        ns = points
+    for n in ns:
+        xs = X[n, :]
+        for m in range(npoints):
+            if (not allow_selfloop) and n == m:
+                continue
+            ys = X[m, :]
+            r = np.linalg.norm(xs - ys)
+            if r <= radius:
+                nnlist[n - points[0]].append(m)
+    if mpisize > 1:
+        nnlist = list(itertools.chain.from_iterable(comm.allgather(nnlist)))
+    return nnlist

+
+
+
+

+[docs]
+def make_neighbor_list(
+    X: np.ndarray,
+    radius: float,
+    allow_selfloop: bool = False,
+    check_allpairs: bool = False,
+    show_progress: bool = False,
+    comm: mpi.Comm = None,
+) -> List[List[int]]:
+    """
+    Create a neighbor list for given points.
+
+    Parameters
+    ----------
+    X : np.ndarray
+        The coordinates of the points.
+    radius : float
+        The radius within which neighbors are considered.
+    allow_selfloop : bool
+        Whether to allow self-loops in the neighbor list.
+    check_allpairs : bool
+        Whether to use the naive all-pairs approach.
+    show_progress : bool
+        Whether to show a progress bar.
+    comm : mpi.Comm, optional
+        The MPI communicator.
+
+    Returns
+    -------
+    List[List[int]]
+        The neighbor list.
+    """
+    if check_allpairs:
+        return make_neighbor_list_naive(
+            X,
+            radius,
+            allow_selfloop=allow_selfloop,
+            show_progress=show_progress,
+            comm=comm,
+        )
+    else:
+        return make_neighbor_list_cell(
+            X,
+            radius,
+            allow_selfloop=allow_selfloop,
+            show_progress=show_progress,
+            comm=comm,
+        )

+
+
+
+

+[docs]
+def load_neighbor_list(filename: PathLike, nnodes: int = None) -> List[List[int]]:
+    """
+    Load a neighbor list from a file.
+
+    Parameters
+    ----------
+    filename : PathLike
+        The path to the file containing the neighbor list.
+    nnodes : int, optional
+        The number of nodes. If None, it will be determined from the file.
+
+    Returns
+    -------
+    List[List[int]]
+        The neighbor list.
+    """
+    if nnodes is None:
+        nnodes = 0
+        with open(filename) as f:
+            for line in f:
+                line = line.split("#")[0].strip()
+                if len(line) == 0:
+                    continue
+                nnodes += 1
+
+    neighbor_list: List[List[int]] = [[] for _ in range(nnodes)]
+    with open(filename) as f:
+        for line in f:
+            line = line.strip().split("#")[0]
+            if len(line) == 0:
+                continue
+            words = line.split()
+            i = int(words[0])
+            nn = [int(w) for w in words[1:]]
+            neighbor_list[i] = nn
+    return neighbor_list

+
+
+
+

+[docs]
+def write_neighbor_list(
+    filename: str,
+    nnlist: List[List[int]],
+    radius: float = None,
+    unit: np.ndarray = None,
+):
+    """
+    Write the neighbor list to a file.
+
+    Parameters
+    ----------
+    filename : str
+        The path to the output file.
+    nnlist : List[List[int]]
+        The neighbor list to write.
+    radius : float, optional
+        The neighborhood radius. Defaults to None.
+    unit : np.ndarray, optional
+        The unit for each coordinate. Defaults to None.
+    """
+    with open(filename, "w") as f:
+        if radius is not None:
+            f.write(f"# radius = {radius}\n")
+        if unit is not None:
+            f.write(f"# unit =")
+            for u in unit:
+                f.write(f" {u}")
+            f.write("\n")
+        for i, nn in enumerate(nnlist):
+            f.write(str(i))
+            for o in sorted(nn):
+                f.write(f" {o}")
+            f.write("\n")

+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Make neighbor-list file from mesh-data file",
+        epilog="""
+Note:
+  - The first column of an input file will be ignored.
+  - UNIT is used for changing aspect ratio (a kind of normalization)
+    - Each coodinate will be divided by the corresponding unit
+    - UNIT is given as a string separated with white space
+      - For example, -u "1.0 0.5 1.0" for 3D case
+  - tqdm python package is required to show progress bar
+""",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("input", type=str, help="input file")
+    parser.add_argument(
+        "-o", "--output", type=str, default="neighborlist.txt", help="output file"
+    )
+    parser.add_argument(
+        "-r", "--radius", type=float, default=1.0, help="neighborhood radius"
+    )
+    parser.add_argument(
+        "-u",
+        "--unit",
+        default=None,
+        help="length unit for each coordinate (see Note)",
+    )
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="Do not show progress bar"
+    )
+    parser.add_argument("--allow-selfloop", action="store_true", help="allow self loop")
+    parser.add_argument(
+        "--check-allpairs",
+        action="store_true",
+        help="check all pairs (bruteforce algorithm)",
+    )
+
+    args = parser.parse_args()
+
+    inputfile = args.input
+    outputfile = args.output
+    radius = args.radius
+
+    X = np.zeros((0, 0))
+
+    if mpi.rank() == 0:
+        X = np.loadtxt(inputfile)
+
+    if mpi.size() > 1:
+        sh = mpi.comm().bcast(X.shape, root=0)
+        if mpi.rank() != 0:
+            X = np.zeros(sh)
+        mpi.comm().Bcast(X, root=0)
+
+    D = X.shape[1] - 1
+
+    if args.unit is None:
+        unit = np.ones(D, dtype=float)
+    else:
+        unit = np.array([float(w) for w in args.unit.split()])
+        if len(unit) != D:
+            print(f"--unit option expects {D} floats as a string but {len(unit)} given")
+            sys.exit(1)
+    X = X[:, 1:] / unit
+
+    nnlist = make_neighbor_list(
+        X,
+        radius,
+        allow_selfloop=args.allow_selfloop,
+        check_allpairs=args.check_allpairs,
+        show_progress=(not args.quiet),
+        comm=mpi.comm(),
+    )
+
+    write_neighbor_list(outputfile, nnlist, radius=radius, unit=unit)
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/read_matrix.html b/manual/v3.0.0/api/_modules/odatse/util/read_matrix.html new file mode 100644 index 00000000..2bacd91e --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/read_matrix.html @@ -0,0 +1,181 @@ + + + + + + + + odatse.util.read_matrix — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.read_matrix

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import Union, List
+
+import numpy as np
+
+
+

+[docs]
+def read_vector(inp: Union[str, List[float]]) -> np.ndarray:
+    """
+    Converts an input string or list of floats into a numpy array vector.
+
+    Parameters
+    ----------
+    inp : Union[str, List[float]]
+        Input data, either as a space-separated string of numbers or a list of floats.
+
+    Returns
+    -------
+    np.ndarray
+        A numpy array representing the vector.
+
+    Raises
+    ------
+    RuntimeError
+        If the input is not a vector.
+    """
+    if isinstance(inp, str):
+        vlist = [float(w) for w in inp.split()]
+    else:
+        vlist = inp
+    v = np.array(vlist)
+    if v.ndim > 1:
+        msg = f"input is not vector ({inp})"
+        raise RuntimeError(msg)
+    return v

+
+
+

+[docs]
+def read_matrix(inp: Union[str, List[List[float]]]) -> np.ndarray:
+    """
+    Converts an input string or list of lists of floats into a numpy array matrix.
+
+    Parameters
+    ----------
+    inp : Union[str, List[List[float]]]
+        Input data, either as a string with rows of space-separated numbers or a list of lists of floats.
+
+    Returns
+    -------
+    np.ndarray
+        A numpy array representing the matrix.
+
+    Raises
+    ------
+    RuntimeError
+        If the input is not a matrix.
+    """
+    if isinstance(inp, str):
+        Alist: List[List[float]] = []
+        for line in inp.split("\n"):
+            if not line.strip():  # empty
+                continue
+            Alist.append([float(w) for w in line.strip().split()])
+    else:
+        Alist = inp
+    A = np.array(Alist)
+    if A.size == 0 or A.ndim == 2:
+        return A
+    msg = f"input is not matrix ({inp})"
+    raise RuntimeError(msg)

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/resampling.html b/manual/v3.0.0/api/_modules/odatse/util/resampling.html new file mode 100644 index 00000000..713a079b --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/resampling.html @@ -0,0 +1,423 @@ + + + + + + + + odatse.util.resampling — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.resampling

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+import typing
+from typing import Union, List, Iterable
+
+import abc
+
+import collections
+import itertools
+import numpy as np
+
+
+

+[docs]
+class Resampler(abc.ABC):
+    @abc.abstractmethod
+    def reset(self, weights: Iterable):
+        ...
+
+    @abc.abstractmethod
+    def sample(self, rs: np.random.RandomState, size=None) -> Union[int, np.ndarray]:
+        ...

+
+
+
+

+[docs]
+class BinarySearch(Resampler):
+    """
+    A resampler that uses binary search to sample based on given weights.
+    """
+    weights_accumulated: List[float]
+    wmax: float
+
+

+[docs]
+    def __init__(self, weights: Iterable):
+        """
+        Initialize the BinarySearch resampler with the given weights.
+
+        Parameters
+        ----------
+        weights : Iterable
+            An iterable of weights.
+        """
+        self.reset(weights)

+
+
+

+[docs]
+    def reset(self, weights: Iterable):
+        """
+        Reset the resampler with new weights.
+
+        Parameters
+        ----------
+        weights : Iterable
+            An iterable of weights.
+        """
+        self.weights_accumulated = list(itertools.accumulate(weights))
+        self.wmax = self.weights_accumulated[-1]

+
+
+    @typing.overload
+    def sample(self, rs: np.random.RandomState) -> int:
+        """
+        Sample a single index based on the weights.
+
+        Parameters
+        ----------
+        rs : np.random.RandomState
+            A random state for generating random numbers.
+
+        Returns
+        -------
+        int
+            A single sampled index.
+        """
+        ...
+
+    @typing.overload
+    def sample(self, rs: np.random.RandomState, size) -> np.ndarray:
+        """
+        Sample multiple indices based on the weights.
+
+        Parameters
+        ----------
+        rs : np.random.RandomState
+            A random state for generating random numbers.
+        size :
+            The number of samples to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of sampled indices.
+        """
+        ...
+
+

+[docs]
+    def sample(self, rs: np.random.RandomState, size=None) -> Union[int, np.ndarray]:
+        """
+        Sample indices based on the weights.
+
+        Parameters
+        ----------
+        rs : np.random.RandomState
+            A random state for generating random numbers.
+        size :
+            The number of samples to generate. If None, a single sample is generated.
+
+        Returns
+        -------
+        int or np.ndarray
+            A single sampled index or an array of sampled indices.
+        """
+        if size is None:
+            return self._sample(self.wmax * rs.rand())
+        else:
+            return np.array([self._sample(r) for r in self.wmax * rs.rand(size)])

+
+
+

+[docs]
+    def _sample(self, r: float) -> int:
+        """
+        Perform a binary search to find the index corresponding to the given random number.
+
+        Parameters
+        ----------
+        r : float
+            A random number scaled by the maximum weight.
+
+        Returns
+        -------
+        int
+            The index corresponding to the random number.
+        """
+        return typing.cast(int, np.searchsorted(self.weights_accumulated, r))

+

+
+
+
+

+[docs]
+class WalkerTable(Resampler):
+    """
+    A resampler that uses Walker's alias method to sample based on given weights.
+    """
+    N: int
+    itable: np.ndarray
+    ptable: np.ndarray
+
+

+[docs]
+    def __init__(self, weights: Iterable):
+        """
+        Initialize the WalkerTable resampler with the given weights.
+
+        Parameters
+        ----------
+        weights : Iterable
+            An iterable of weights.
+        """
+        self.reset(weights)

+
+
+

+[docs]
+    def reset(self, weights: Iterable):
+        """
+        Reset the resampler with new weights.
+
+        Parameters
+        ----------
+        weights : Iterable
+            An iterable of weights.
+        """
+        self.ptable = np.array(weights).astype(np.float64).flatten()
+        self.N = len(self.ptable)
+        self.itable = np.full(self.N, -1)
+        mean = self.ptable.mean()
+        self.ptable -= mean
+        shorter = collections.deque([i for i, p in enumerate(self.ptable) if p < 0.0])
+        longer = collections.deque([i for i, p in enumerate(self.ptable) if p >= 0.0])
+
+        while len(longer) > 0 and len(shorter) > 0:
+            ilong = longer[0]
+            ishort = shorter.popleft()
+            self.itable[ishort] = ilong
+            self.ptable[ilong] += self.ptable[ishort]
+            if self.ptable[ilong] <= 0.0:
+                longer.popleft()
+                shorter.append(ilong)
+        self.ptable += mean
+        self.ptable *= 1.0 / mean

+
+
+    @typing.overload
+    def sample(self, rs: np.random.RandomState) -> int:
+        """
+        Sample a single index based on the weights.
+
+        Parameters
+        ----------
+        rs : np.random.RandomState
+            A random state for generating random numbers.
+
+        Returns
+        -------
+        int
+            A single sampled index.
+        """
+        ...
+
+    @typing.overload
+    def sample(self, rs: np.random.RandomState, size) -> np.ndarray:
+        """
+        Sample multiple indices based on the weights.
+
+        Parameters
+        ----------
+        rs : np.random.RandomState
+            A random state for generating random numbers.
+        size :
+            The number of samples to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of sampled indices.
+        """
+        ...
+
+

+[docs]
+    def sample(self, rs: np.random.RandomState, size=None) -> Union[int, np.ndarray]:
+        """
+        Sample indices based on the weights.
+
+        Parameters
+        ----------
+        rs : np.random.RandomState
+            A random state for generating random numbers.
+        size :
+            The number of samples to generate. If None, a single sample is generated.
+
+        Returns
+        -------
+        int or np.ndarray
+            A single sampled index or an array of sampled indices.
+        """
+        if size is None:
+            r = rs.rand() * self.N
+            return self._sample(r)
+        else:
+            r = rs.rand(size) * self.N
+            i = np.floor(r).astype(np.int64)
+            p = r - i
+            ret = np.where(p < self.ptable[i], i, self.itable[i])
+            return ret

+
+
+

+[docs]
+    def _sample(self, r: float) -> int:
+        """
+        Perform a sampling operation based on the given random number.
+
+        Parameters
+        ----------
+        r : float
+            A random number scaled by the number of weights.
+
+        Returns
+        -------
+        int
+            The index corresponding to the random number.
+        """
+        i = int(np.floor(r))
+        p = r - i
+        if p < self.ptable[i]:
+            return i
+        else:
+            return self.itable[i]

+

+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="resampling test")
+    parser.add_argument(
+        "-s", "--seed", type=int, default=12345, help="random number seed"
+    )
+    parser.add_argument("-m", "--method", default="walker", help="method to resample")
+    parser.add_argument("-N", type=int, default=100000, help="Number of samples")
+
+    args = parser.parse_args()
+
+    rs = np.random.RandomState(args.seed)
+
+    ps = [0.0, 1.0, 2.0, 3.0]
+    # ps = rs.rand(5)
+    S = np.sum(ps)
+    if args.method == "walker":
+        resampler = WalkerTable(ps)
+    else:
+        resampler = BinarySearch(ps)
+    samples = resampler.sample(rs, args.N)
+
+    print("#i result exact diff")
+    for i, p in enumerate(ps):
+        r = np.count_nonzero(samples == i) / args.N
+        print(f"{i} {r} {p/S} {r - p/S}")
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/separateT.html b/manual/v3.0.0/api/_modules/odatse/util/separateT.html new file mode 100644 index 00000000..3aa2c8c8 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/separateT.html @@ -0,0 +1,221 @@ + + + + + + + + odatse.util.separateT — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.separateT

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import Dict, List, Optional
+import pathlib
+from os import PathLike
+from collections import namedtuple
+
+import numpy as np
+
+from odatse import mpi
+
+Entry = namedtuple("Entry", ["step", "walker", "fx", "xs"])
+
+
+

+[docs]
+def separateT(
+    Ts: np.ndarray,
+    nwalkers: int,
+    output_dir: PathLike,
+    comm: Optional[mpi.Comm],
+    use_beta: bool,
+    buffer_size: int = 10000,
+) -> None:
+    """
+    Separates and processes temperature data for quantum beam diffraction experiments.
+
+    Parameters
+    ----------
+    Ts : np.ndarray
+        Array of temperature values.
+    nwalkers : int
+        Number of walkers.
+    output_dir : PathLike
+        Directory to store the output files.
+    comm : mpi.Comm, optional
+        MPI communicator for parallel processing.
+    use_beta : bool
+        Flag to determine if beta values are used instead of temperature.
+    buffer_size : int, optional
+        Size of the buffer for reading input data. Default is 10000.
+    """
+    if comm is None:
+        mpisize = 1
+        mpirank = 0
+    else:
+        mpisize = comm.size
+        mpirank = comm.rank
+    buffer_size = int(np.ceil(buffer_size / nwalkers)) * nwalkers
+    output_dir = pathlib.Path(output_dir)
+    proc_dir = output_dir / str(mpirank)
+
+    T2idx = {T: i for i, T in enumerate(Ts)}
+    T2rank = {}
+    results = []
+    for rank, Ts_local in enumerate(np.array_split(Ts, mpisize)):
+        d: Dict[str, List[Entry]] = {}
+        for T in Ts_local:
+            T2rank[str(T)] = rank
+            d[str(T)] = []
+        results.append(d)
+
+    # write file header
+    for T in Ts[mpirank * nwalkers : (mpirank + 1) * nwalkers]:
+        idx = T2idx[T]
+        with open(output_dir / f"result_T{idx}.txt", "w") as f_out:
+            if use_beta:
+                f_out.write(f"# beta = {T}\n")
+            else:
+                f_out.write(f"# T = {T}\n")
+
+    f_in = open(proc_dir / "result.txt")
+    EOF = False
+    while not EOF:
+        for i in range(len(results)):
+            for key in results[i].keys():
+                results[i][key] = []
+        for _ in range(buffer_size):
+            line = f_in.readline()
+            if line == "":
+                EOF = True
+                break
+            line = line.split("#")[0].strip()
+            if len(line) == 0:
+                continue
+            words = line.split()
+            step = int(words[0])
+            walker = mpirank * nwalkers + int(words[1])
+            Tstr = words[2]
+            fx = words[3]
+            xs = words[4:]
+            entry = Entry(step=step, walker=walker, fx=fx, xs=xs)
+            rank = T2rank[Tstr]
+            results[rank][Tstr].append(entry)
+        if mpisize > 1:
+            results2 = comm.alltoall(results)
+        else:
+            results2 = results
+        d = results2[0]
+        for i in range(1, len(results2)):
+            for key in d.keys():
+                d[key].extend(results2[i][key])
+        for T in Ts[mpirank * nwalkers : (mpirank + 1) * nwalkers]:
+            idx = T2idx[T]
+            d[str(T)].sort(key=lambda e: e.step)
+            with open(output_dir / f"result_T{idx}.txt", "a") as f_out:
+                for e in d[str(T)]:
+                    f_out.write(f"{e.step} ")
+                    f_out.write(f"{e.walker} ")
+                    f_out.write(f"{e.fx} ")
+                    for x in e.xs:
+                        f_out.write(f"{x} ")
+                    f_out.write("\n")

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_modules/odatse/util/toml.html b/manual/v3.0.0/api/_modules/odatse/util/toml.html new file mode 100644 index 00000000..d7713f24 --- /dev/null +++ b/manual/v3.0.0/api/_modules/odatse/util/toml.html @@ -0,0 +1,165 @@ + + + + + + + + odatse.util.toml — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +

Source code for odatse.util.toml

+# SPDX-License-Identifier: MPL-2.0
+#
+# ODAT-SE -- an open framework for data analysis
+# Copyright (C) 2020- The University of Tokyo
+#
+# This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from typing import MutableMapping, Any
+
+from ..mpi import rank
+
+USE_TOML = False
+OLD_TOMLI_API = False
+
+try:
+    import tomli
+
+    if tomli.__version__ < "1.2.0":
+        OLD_TOMLI_API = True
+except ImportError:
+    try:
+        import toml
+
+        USE_TOML = True
+        if rank() == 0:
+            print("WARNING: tomli is not found and toml is found.")
+            print("         use of toml package is left for compatibility.")
+            print("         please install tomli package.")
+            print("HINT: python3 -m pip install tomli")
+            print()
+    except ImportError:
+        if rank() == 0:
+            print("ERROR: tomli is not found")
+            print("HINT: python3 -m pip install tomli")
+        raise
+
+
+

+[docs]
+def load(path: str) -> MutableMapping[str, Any]:
+    """read TOML file
+
+    Parameters
+    ----------
+    path: str
+        File path to an input TOML file
+
+    Returns
+    -------
+    toml_dict: MutableMapping[str, Any]
+        Dictionary representing TOML file
+
+    """
+    if USE_TOML:
+        return toml.load(path)
+    else:
+        if OLD_TOMLI_API:
+            with open(path, "r") as f:
+                return tomli.load(f)
+        else:
+            with open(path, "rb") as f:
+                return tomli.load(f)

+
+
+ +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/_sources/index.rst.txt b/manual/v3.0.0/api/_sources/index.rst.txt new file mode 100644 index 00000000..c3cba7b1 --- /dev/null +++ b/manual/v3.0.0/api/_sources/index.rst.txt @@ -0,0 +1,21 @@ +.. ODAT-SE API documentation master file, created by + sphinx-quickstart on Thu Oct 31 10:18:29 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to ODAT-SE API's documentation! +======================================= + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + modules + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/manual/v3.0.0/api/_sources/modules.rst.txt b/manual/v3.0.0/api/_sources/modules.rst.txt new file mode 100644 index 00000000..3a33c17e --- /dev/null +++ b/manual/v3.0.0/api/_sources/modules.rst.txt @@ -0,0 +1,7 @@ +odatse +====== + +.. toctree:: + :maxdepth: 1 + + odatse diff --git a/manual/v3.0.0/api/_sources/odatse._info.rst.txt b/manual/v3.0.0/api/_sources/odatse._info.rst.txt new file mode 100644 index 00000000..37d6f1ed --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse._info.rst.txt @@ -0,0 +1,7 @@ +odatse.\_info module +==================== + +.. automodule:: odatse._info + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse._initialize.rst.txt b/manual/v3.0.0/api/_sources/odatse._initialize.rst.txt new file mode 100644 index 00000000..ab44e17b --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse._initialize.rst.txt @@ -0,0 +1,7 @@ +odatse.\_initialize module +========================== + +.. automodule:: odatse._initialize + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse._main.rst.txt b/manual/v3.0.0/api/_sources/odatse._main.rst.txt new file mode 100644 index 00000000..122d809c --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse._main.rst.txt @@ -0,0 +1,7 @@ +odatse.\_main module +==================== + +.. automodule:: odatse._main + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse._runner.rst.txt b/manual/v3.0.0/api/_sources/odatse._runner.rst.txt new file mode 100644 index 00000000..7a8916f7 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse._runner.rst.txt @@ -0,0 +1,7 @@ +odatse.\_runner module +====================== + +.. automodule:: odatse._runner + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm._algorithm.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm._algorithm.rst.txt new file mode 100644 index 00000000..a1465555 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm._algorithm.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.\_algorithm module +=================================== + +.. automodule:: odatse.algorithm._algorithm + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.bayes.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.bayes.rst.txt new file mode 100644 index 00000000..66f571cc --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.bayes.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.bayes module +============================= + +.. automodule:: odatse.algorithm.bayes + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.exchange.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.exchange.rst.txt new file mode 100644 index 00000000..6f3427b0 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.exchange.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.exchange module +================================ + +.. automodule:: odatse.algorithm.exchange + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.mapper_mpi.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.mapper_mpi.rst.txt new file mode 100644 index 00000000..ce3c74af --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.mapper_mpi.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.mapper\_mpi module +=================================== + +.. automodule:: odatse.algorithm.mapper_mpi + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.min_search.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.min_search.rst.txt new file mode 100644 index 00000000..09d389e8 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.min_search.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.min\_search module +=================================== + +.. automodule:: odatse.algorithm.min_search + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.montecarlo.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.montecarlo.rst.txt new file mode 100644 index 00000000..0cc7cb15 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.montecarlo.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.montecarlo module +================================== + +.. automodule:: odatse.algorithm.montecarlo + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.pamc.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.pamc.rst.txt new file mode 100644 index 00000000..1abe5109 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.pamc.rst.txt @@ -0,0 +1,7 @@ +odatse.algorithm.pamc module +============================ + +.. automodule:: odatse.algorithm.pamc + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.algorithm.rst.txt b/manual/v3.0.0/api/_sources/odatse.algorithm.rst.txt new file mode 100644 index 00000000..1d94c41f --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.algorithm.rst.txt @@ -0,0 +1,21 @@ +odatse.algorithm package +======================== + +.. automodule:: odatse.algorithm + :members: + :show-inheritance: + :private-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + odatse.algorithm._algorithm + odatse.algorithm.bayes + odatse.algorithm.exchange + odatse.algorithm.mapper_mpi + odatse.algorithm.min_search + odatse.algorithm.montecarlo + odatse.algorithm.pamc diff --git a/manual/v3.0.0/api/_sources/odatse.domain._domain.rst.txt b/manual/v3.0.0/api/_sources/odatse.domain._domain.rst.txt new file mode 100644 index 00000000..475476fd --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.domain._domain.rst.txt @@ -0,0 +1,7 @@ +odatse.domain.\_domain module +============================= + +.. automodule:: odatse.domain._domain + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.domain.meshgrid.rst.txt b/manual/v3.0.0/api/_sources/odatse.domain.meshgrid.rst.txt new file mode 100644 index 00000000..45308619 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.domain.meshgrid.rst.txt @@ -0,0 +1,7 @@ +odatse.domain.meshgrid module +============================= + +.. automodule:: odatse.domain.meshgrid + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.domain.region.rst.txt b/manual/v3.0.0/api/_sources/odatse.domain.region.rst.txt new file mode 100644 index 00000000..3b58537f --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.domain.region.rst.txt @@ -0,0 +1,7 @@ +odatse.domain.region module +=========================== + +.. automodule:: odatse.domain.region + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.domain.rst.txt b/manual/v3.0.0/api/_sources/odatse.domain.rst.txt new file mode 100644 index 00000000..ac5f6925 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.domain.rst.txt @@ -0,0 +1,17 @@ +odatse.domain package +===================== + +.. automodule:: odatse.domain + :members: + :show-inheritance: + :private-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + odatse.domain._domain + odatse.domain.meshgrid + odatse.domain.region diff --git a/manual/v3.0.0/api/_sources/odatse.exception.rst.txt b/manual/v3.0.0/api/_sources/odatse.exception.rst.txt new file mode 100644 index 00000000..5ff7200e --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.exception.rst.txt @@ -0,0 +1,7 @@ +odatse.exception module +======================= + +.. automodule:: odatse.exception + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.mpi.rst.txt b/manual/v3.0.0/api/_sources/odatse.mpi.rst.txt new file mode 100644 index 00000000..200fd450 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.mpi.rst.txt @@ -0,0 +1,7 @@ +odatse.mpi module +================= + +.. automodule:: odatse.mpi + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.rst.txt b/manual/v3.0.0/api/_sources/odatse.rst.txt new file mode 100644 index 00000000..2450ea3b --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.rst.txt @@ -0,0 +1,31 @@ +odatse package +============== + +.. automodule:: odatse + :members: + :show-inheritance: + :private-members: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 1 + + odatse.algorithm + odatse.domain + odatse.solver + odatse.util + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + odatse._info + odatse._initialize + odatse._main + odatse._runner + odatse.exception + odatse.mpi diff --git a/manual/v3.0.0/api/_sources/odatse.solver._solver.rst.txt b/manual/v3.0.0/api/_sources/odatse.solver._solver.rst.txt new file mode 100644 index 00000000..019a394f --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.solver._solver.rst.txt @@ -0,0 +1,7 @@ +odatse.solver.\_solver module +============================= + +.. automodule:: odatse.solver._solver + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.solver.analytical.rst.txt b/manual/v3.0.0/api/_sources/odatse.solver.analytical.rst.txt new file mode 100644 index 00000000..456ee162 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.solver.analytical.rst.txt @@ -0,0 +1,7 @@ +odatse.solver.analytical module +=============================== + +.. automodule:: odatse.solver.analytical + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.solver.function.rst.txt b/manual/v3.0.0/api/_sources/odatse.solver.function.rst.txt new file mode 100644 index 00000000..72c839e5 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.solver.function.rst.txt @@ -0,0 +1,7 @@ +odatse.solver.function module +============================= + +.. automodule:: odatse.solver.function + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.solver.rst.txt b/manual/v3.0.0/api/_sources/odatse.solver.rst.txt new file mode 100644 index 00000000..a854a880 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.solver.rst.txt @@ -0,0 +1,17 @@ +odatse.solver package +===================== + +.. automodule:: odatse.solver + :members: + :show-inheritance: + :private-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + odatse.solver._solver + odatse.solver.analytical + odatse.solver.function diff --git a/manual/v3.0.0/api/_sources/odatse.util.graph.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.graph.rst.txt new file mode 100644 index 00000000..361d976a --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.graph.rst.txt @@ -0,0 +1,7 @@ +odatse.util.graph module +======================== + +.. automodule:: odatse.util.graph + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.limitation.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.limitation.rst.txt new file mode 100644 index 00000000..c3c235d7 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.limitation.rst.txt @@ -0,0 +1,7 @@ +odatse.util.limitation module +============================= + +.. automodule:: odatse.util.limitation + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.logger.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.logger.rst.txt new file mode 100644 index 00000000..af38d240 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.logger.rst.txt @@ -0,0 +1,7 @@ +odatse.util.logger module +========================= + +.. automodule:: odatse.util.logger + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.mapping.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.mapping.rst.txt new file mode 100644 index 00000000..3171120f --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.mapping.rst.txt @@ -0,0 +1,7 @@ +odatse.util.mapping module +========================== + +.. automodule:: odatse.util.mapping + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.neighborlist.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.neighborlist.rst.txt new file mode 100644 index 00000000..2736b613 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.neighborlist.rst.txt @@ -0,0 +1,7 @@ +odatse.util.neighborlist module +=============================== + +.. automodule:: odatse.util.neighborlist + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.read_matrix.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.read_matrix.rst.txt new file mode 100644 index 00000000..b05fa52f --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.read_matrix.rst.txt @@ -0,0 +1,7 @@ +odatse.util.read\_matrix module +=============================== + +.. automodule:: odatse.util.read_matrix + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.resampling.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.resampling.rst.txt new file mode 100644 index 00000000..c9fc2291 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.resampling.rst.txt @@ -0,0 +1,7 @@ +odatse.util.resampling module +============================= + +.. automodule:: odatse.util.resampling + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.rst.txt new file mode 100644 index 00000000..22c8ed15 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.rst.txt @@ -0,0 +1,23 @@ +odatse.util package +=================== + +.. automodule:: odatse.util + :members: + :show-inheritance: + :private-members: + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + odatse.util.graph + odatse.util.limitation + odatse.util.logger + odatse.util.mapping + odatse.util.neighborlist + odatse.util.read_matrix + odatse.util.resampling + odatse.util.separateT + odatse.util.toml diff --git a/manual/v3.0.0/api/_sources/odatse.util.separateT.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.separateT.rst.txt new file mode 100644 index 00000000..77176682 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.separateT.rst.txt @@ -0,0 +1,7 @@ +odatse.util.separateT module +============================ + +.. automodule:: odatse.util.separateT + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_sources/odatse.util.toml.rst.txt b/manual/v3.0.0/api/_sources/odatse.util.toml.rst.txt new file mode 100644 index 00000000..c1f83185 --- /dev/null +++ b/manual/v3.0.0/api/_sources/odatse.util.toml.rst.txt @@ -0,0 +1,7 @@ +odatse.util.toml module +======================= + +.. automodule:: odatse.util.toml + :members: + :show-inheritance: + :private-members: diff --git a/manual/v3.0.0/api/_static/_sphinx_javascript_frameworks_compat.js b/manual/v3.0.0/api/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..81415803 --- /dev/null +++ b/manual/v3.0.0/api/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,123 @@ +/* Compatability shim for jQuery and underscores.js. + * + * Copyright Sphinx contributors + * Released under the two clause BSD licence + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/manual/v3.0.0/api/_static/basic.css b/manual/v3.0.0/api/_static/basic.css new file mode 100644 index 00000000..7ebbd6d0 --- /dev/null +++ b/manual/v3.0.0/api/_static/basic.css @@ -0,0 +1,914 @@ +/* + * Sphinx stylesheet -- basic theme. + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin-top: 10px; +} + +ul.search li { + padding: 5px 0; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/manual/v3.0.0/api/_static/css/badge_only.css b/manual/v3.0.0/api/_static/css/badge_only.css new file mode 100644 index 00000000..88ba55b9 --- /dev/null +++ b/manual/v3.0.0/api/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px} \ No newline at end of file diff --git a/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Bold.woff b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Bold.woff2 b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Regular.woff b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Regular.woff2 b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.eot b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.svg b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.ttf b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.woff b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.woff2 b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-bold-italic.woff b/manual/v3.0.0/api/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-bold-italic.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-bold-italic.woff2 b/manual/v3.0.0/api/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-bold.woff b/manual/v3.0.0/api/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-bold.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-bold.woff2 b/manual/v3.0.0/api/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-bold.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-normal-italic.woff b/manual/v3.0.0/api/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-normal-italic.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-normal-italic.woff2 b/manual/v3.0.0/api/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-normal.woff b/manual/v3.0.0/api/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-normal.woff differ diff --git a/manual/v3.0.0/api/_static/css/fonts/lato-normal.woff2 b/manual/v3.0.0/api/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/manual/v3.0.0/api/_static/css/fonts/lato-normal.woff2 differ diff --git a/manual/v3.0.0/api/_static/css/theme.css b/manual/v3.0.0/api/_static/css/theme.css new file mode 100644 index 00000000..0f14f106 --- /dev/null +++ b/manual/v3.0.0/api/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search .wy-dropdown>aactive,.wy-side-nav-search .wy-dropdown>afocus,.wy-side-nav-search>a:hover,.wy-side-nav-search>aactive,.wy-side-nav-search>afocus{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon,.wy-side-nav-search>a.icon{display:block}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.switch-menus{position:relative;display:block;margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-side-nav-search>div.switch-menus>div.language-switch,.wy-side-nav-search>div.switch-menus>div.version-switch{display:inline-block;padding:.2em}.wy-side-nav-search>div.switch-menus>div.language-switch select,.wy-side-nav-search>div.switch-menus>div.version-switch select{display:inline-block;margin-right:-2rem;padding-right:2rem;max-width:240px;text-align-last:center;background:none;border:none;border-radius:0;box-shadow:none;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-size:1em;font-weight:400;color:hsla(0,0%,100%,.3);cursor:pointer;appearance:none;-webkit-appearance:none;-moz-appearance:none}.wy-side-nav-search>div.switch-menus>div.language-switch select:active,.wy-side-nav-search>div.switch-menus>div.language-switch select:focus,.wy-side-nav-search>div.switch-menus>div.language-switch select:hover,.wy-side-nav-search>div.switch-menus>div.version-switch select:active,.wy-side-nav-search>div.switch-menus>div.version-switch select:focus,.wy-side-nav-search>div.switch-menus>div.version-switch select:hover{background:hsla(0,0%,100%,.1);color:hsla(0,0%,100%,.5)}.wy-side-nav-search>div.switch-menus>div.language-switch select option,.wy-side-nav-search>div.switch-menus>div.version-switch select option{color:#000}.wy-side-nav-search>div.switch-menus>div.language-switch:has(>select):after,.wy-side-nav-search>div.switch-menus>div.version-switch:has(>select):after{display:inline-block;width:1.5em;height:100%;padding:.1em;content:"\f0d7";font-size:1em;line-height:1.2em;font-family:FontAwesome;text-align:center;pointer-events:none;box-sizing:border-box}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel,.rst-content .menuselection{font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .guilabel,.rst-content .menuselection{border:1px solid #7fbbe3;background:#e7f2fa}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/manual/v3.0.0/api/_static/doctools.js b/manual/v3.0.0/api/_static/doctools.js new file mode 100644 index 00000000..0398ebb9 --- /dev/null +++ b/manual/v3.0.0/api/_static/doctools.js @@ -0,0 +1,149 @@ +/* + * Base JavaScript utilities for all Sphinx HTML documentation. + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/manual/v3.0.0/api/_static/documentation_options.js b/manual/v3.0.0/api/_static/documentation_options.js new file mode 100644 index 00000000..7e4c114f --- /dev/null +++ b/manual/v3.0.0/api/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/manual/v3.0.0/api/_static/file.png b/manual/v3.0.0/api/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/manual/v3.0.0/api/_static/file.png differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.eot b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.eot new file mode 100644 index 00000000..3361183a Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.eot differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.ttf b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.ttf new file mode 100644 index 00000000..29f691d5 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.ttf differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.woff b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.woff differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.woff2 b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bold.woff2 differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.eot b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.eot new file mode 100644 index 00000000..3d415493 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.eot differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.ttf b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.ttf new file mode 100644 index 00000000..f402040b Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.ttf differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.woff b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.woff differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.woff2 b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-bolditalic.woff2 differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.eot b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.eot new file mode 100644 index 00000000..3f826421 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.eot differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.ttf b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.ttf new file mode 100644 index 00000000..b4bfc9b2 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.ttf differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.woff b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.woff differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.woff2 b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-italic.woff2 differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.eot b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.eot new file mode 100644 index 00000000..11e3f2a5 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.eot differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.ttf b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.ttf new file mode 100644 index 00000000..74decd9e Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.ttf differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.woff b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.woff differ diff --git a/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.woff2 b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/Lato/lato-regular.woff2 differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot new file mode 100644 index 00000000..79dc8efe Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf new file mode 100644 index 00000000..df5d1df2 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot new file mode 100644 index 00000000..2f7ca78a Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf new file mode 100644 index 00000000..eb52a790 Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff differ diff --git a/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/manual/v3.0.0/api/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 differ diff --git a/manual/v3.0.0/api/_static/jquery.js b/manual/v3.0.0/api/_static/jquery.js new file mode 100644 index 00000000..c4c6022f --- /dev/null +++ b/manual/v3.0.0/api/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t a.language.name.localeCompare(b.language.name)); + + const languagesHTML = ` +
+
Languages
+ ${languages + .map( + (translation) => ` +
+ ${translation.language.code} +
+ `, + ) + .join("\n")} +
+ `; + return languagesHTML; + } + + function renderVersions(config) { + if (!config.versions.active.length) { + return ""; + } + const versionsHTML = ` +
+
Versions
+ ${config.versions.active + .map( + (version) => ` +
+ ${version.slug} +
+ `, + ) + .join("\n")} +
+ `; + return versionsHTML; + } + + function renderDownloads(config) { + if (!Object.keys(config.versions.current.downloads).length) { + return ""; + } + const downloadsNameDisplay = { + pdf: "PDF", + epub: "Epub", + htmlzip: "HTML", + }; + + const downloadsHTML = ` +
+
Downloads
+ ${Object.entries(config.versions.current.downloads) + .map( + ([name, url]) => ` +
+ ${downloadsNameDisplay[name]} +
+ `, + ) + .join("\n")} +
+ `; + return downloadsHTML; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const flyout = ` +
+ + Read the Docs + v: ${config.versions.current.slug} + + +
+
+ ${renderLanguages(config)} + ${renderVersions(config)} + ${renderDownloads(config)} +
+
On Read the Docs
+
+ Project Home +
+
+ Builds +
+
+ Downloads +
+
+
+
Search
+
+
+ +
+
+
+
+ + Hosted by Read the Docs + +
+
+ `; + + // Inject the generated flyout into the body HTML element. + document.body.insertAdjacentHTML("beforeend", flyout); + + // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout. + document + .querySelector("#flyout-search-form") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + }) +} + +if (themeLanguageSelector || themeVersionSelector) { + function onSelectorSwitch(event) { + const option = event.target.selectedIndex; + const item = event.target.options[option]; + window.location.href = item.dataset.url; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const versionSwitch = document.querySelector( + "div.switch-menus > div.version-switch", + ); + if (themeVersionSelector) { + let versions = config.versions.active; + if (config.versions.current.hidden || config.versions.current.type === "external") { + versions.unshift(config.versions.current); + } + const versionSelect = ` + + `; + + versionSwitch.innerHTML = versionSelect; + versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + + const languageSwitch = document.querySelector( + "div.switch-menus > div.language-switch", + ); + + if (themeLanguageSelector) { + if (config.projects.translations.length) { + // Add the current language to the options on the selector + let languages = config.projects.translations.concat( + config.projects.current, + ); + languages = languages.sort((a, b) => + a.language.name.localeCompare(b.language.name), + ); + + const languageSelect = ` + + `; + + languageSwitch.innerHTML = languageSelect; + languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + else { + languageSwitch.remove(); + } + } + }); +} + +document.addEventListener("readthedocs-addons-data-ready", function (event) { + // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. + document + .querySelector("[role='search'] input") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); +}); \ No newline at end of file diff --git a/manual/v3.0.0/api/_static/language_data.js b/manual/v3.0.0/api/_static/language_data.js new file mode 100644 index 00000000..c7fe6c6f --- /dev/null +++ b/manual/v3.0.0/api/_static/language_data.js @@ -0,0 +1,192 @@ +/* + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/manual/v3.0.0/api/_static/minus.png b/manual/v3.0.0/api/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/manual/v3.0.0/api/_static/minus.png differ diff --git a/manual/v3.0.0/api/_static/plus.png b/manual/v3.0.0/api/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/manual/v3.0.0/api/_static/plus.png differ diff --git a/manual/v3.0.0/api/_static/pygments.css b/manual/v3.0.0/api/_static/pygments.css new file mode 100644 index 00000000..84ab3030 --- /dev/null +++ b/manual/v3.0.0/api/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #008000; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #9C6500 } /* Comment.Preproc */ +.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #E40000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #008400 } /* Generic.Inserted */ +.highlight .go { color: #717171 } /* Generic.Output */ +.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #008000 } /* Keyword.Pseudo */ +.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #B00040 } /* Keyword.Type */ +.highlight .m { color: #666666 } /* Literal.Number */ +.highlight .s { color: #BA2121 } /* Literal.String */ +.highlight .na { color: #687822 } /* Name.Attribute */ +.highlight .nb { color: #008000 } /* Name.Builtin */ +.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.highlight .no { color: #880000 } /* Name.Constant */ +.highlight .nd { color: #AA22FF } /* Name.Decorator */ +.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #0000FF } /* Name.Function */ +.highlight .nl { color: #767600 } /* Name.Label */ +.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #19177C } /* Name.Variable */ +.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #666666 } /* Literal.Number.Bin */ +.highlight .mf { color: #666666 } /* Literal.Number.Float */ +.highlight .mh { color: #666666 } /* Literal.Number.Hex */ +.highlight .mi { color: #666666 } /* Literal.Number.Integer */ +.highlight .mo { color: #666666 } /* Literal.Number.Oct */ +.highlight .sa { color: #BA2121 } /* Literal.String.Affix */ +.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */ +.highlight .sc { color: #BA2121 } /* Literal.String.Char */ +.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #BA2121 } /* Literal.String.Double */ +.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */ +.highlight .sx { color: #008000 } /* Literal.String.Other */ +.highlight .sr { color: #A45A77 } /* Literal.String.Regex */ +.highlight .s1 { color: #BA2121 } /* Literal.String.Single */ +.highlight .ss { color: #19177C } /* Literal.String.Symbol */ +.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #0000FF } /* Name.Function.Magic */ +.highlight .vc { color: #19177C } /* Name.Variable.Class */ +.highlight .vg { color: #19177C } /* Name.Variable.Global */ +.highlight .vi { color: #19177C } /* Name.Variable.Instance */ +.highlight .vm { color: #19177C } /* Name.Variable.Magic */ +.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/manual/v3.0.0/api/_static/searchtools.js b/manual/v3.0.0/api/_static/searchtools.js new file mode 100644 index 00000000..2c774d17 --- /dev/null +++ b/manual/v3.0.0/api/_static/searchtools.js @@ -0,0 +1,632 @@ +/* + * Sphinx JavaScript utilities for the full-text search. + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + SearchResultKind.title, + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + SearchResultKind.text, + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/manual/v3.0.0/api/_static/sphinx_highlight.js b/manual/v3.0.0/api/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/manual/v3.0.0/api/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/manual/v3.0.0/api/genindex.html b/manual/v3.0.0/api/genindex.html new file mode 100644 index 00000000..205c56a7 --- /dev/null +++ b/manual/v3.0.0/api/genindex.html @@ -0,0 +1,1148 @@ + + + + + + + + Index — ODAT-SE API documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Index
    • +
  • +
    • +
+
+
+
+
+ + +

Index

+ +
+ _ + | A + | B + | C + | D + | E + | F + | G + | H + | I + | J + | L + | M + | N + | O + | P + | Q + | R + | S + | T + | U + | W + | X + +
+

_

+ + + +
+ +

A

+ + + +
+ +

B

+ + + +
+ +

C

+ + + +
+ +

D

+ + + +
+ +

E

+ + + +
+ +

F

+ + + +
+ +

G

+ + +
+ +

H

+ + +
+ +

I

+ + + +
+ +

J

+ + +
+ +

L

+ + + +
+ +

M

+ + + +
+ +

N

+ + + +
+ +

O

+ + + +
    +
  • + odatse + +
    • +
  • + odatse._info + +
    • +
  • + odatse._initialize + +
    • +
  • + odatse._main + +
    • +
  • + odatse._runner + +
    • +
  • + odatse.algorithm + +
    • +
  • + odatse.algorithm._algorithm + +
    • +
  • + odatse.algorithm.bayes + +
    • +
  • + odatse.algorithm.exchange + +
    • +
  • + odatse.algorithm.mapper_mpi + +
    • +
  • + odatse.algorithm.min_search + +
    • +
  • + odatse.algorithm.montecarlo + +
    • +
  • + odatse.algorithm.pamc + +
    • +
  • + odatse.domain + +
    • +
  • + odatse.domain._domain + +
    • +
  • + odatse.domain.meshgrid + +
    • +
  • + odatse.domain.region + +
    • +
+ +

P

+ + + +
+ +

Q

+ + + +
+ +

R

+ + + +
+ +

S

+ + + +
+ +

T

+ + + +
+ +

U

+ + + +
+ +

W

+ + + +
+ +

X

+ + + +
+ + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/index.html b/manual/v3.0.0/api/index.html new file mode 100644 index 00000000..647a0a27 --- /dev/null +++ b/manual/v3.0.0/api/index.html @@ -0,0 +1,142 @@ + + + + + + + + + Welcome to ODAT-SE API’s documentation! — ODAT-SE API documentation + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/modules.html b/manual/v3.0.0/api/modules.html new file mode 100644 index 00000000..18b22474 --- /dev/null +++ b/manual/v3.0.0/api/modules.html @@ -0,0 +1,117 @@ + + + + + + + + + odatse — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/objects.inv b/manual/v3.0.0/api/objects.inv new file mode 100644 index 00000000..5b24385e Binary files /dev/null and b/manual/v3.0.0/api/objects.inv differ diff --git a/manual/v3.0.0/api/odatse._info.html b/manual/v3.0.0/api/odatse._info.html new file mode 100644 index 00000000..01d07521 --- /dev/null +++ b/manual/v3.0.0/api/odatse._info.html @@ -0,0 +1,194 @@ + + + + + + + + + odatse._info module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse._info module

+
+
+class odatse._info.Info(d: MutableMapping | None = None)[source]
+

Bases: object

+

A class to represent the information structure for the data-analysis software.

+

Initialize the Info object.

+
+
Parameters:
+

d (MutableMapping (optional)) – A dictionary to initialize the Info object.

+
+
+
+
+__init__(d: MutableMapping | None = None)[source]
+

Initialize the Info object.

+
+
Parameters:
+

d (MutableMapping (optional)) – A dictionary to initialize the Info object.

+
+
+
+ +
+
+_cleanup() → None[source]
+

Reset the Info object to its default state.

+
+ +
+
+from_dict(d: MutableMapping) → None[source]
+

Initialize the Info object from a dictionary.

+
+
Parameters:
+

d (MutableMapping) – A dictionary containing the information to initialize the Info object.

+
+
Raises:
+

exception.InputError – If any required section is missing in the input dictionary.

+
+
+
+ +
+
+classmethod from_file(file_name, fmt='', **kwargs)[source]
+

Create an Info object from a file.

+
+
Parameters:
+
    +

  • file_name (str) – The name of the file to load the information from.

    • +

  • fmt (str) – The format of the file (default is “”).

    • +

  • **kwargs – Additional keyword arguments.

    • +
+
+
Returns:
+

An Info object initialized with the data from the file.

+
+
Return type:
+

Info

+
+
Raises:
+

ValueError – If the file format is unsupported.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse._initialize.html b/manual/v3.0.0/api/odatse._initialize.html new file mode 100644 index 00000000..375d631e --- /dev/null +++ b/manual/v3.0.0/api/odatse._initialize.html @@ -0,0 +1,140 @@ + + + + + + + + + odatse._initialize module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse._initialize module

+
+
+odatse._initialize.initialize()[source]
+

Initialize for main function by parsing commandline arguments and loading input files

+
+
Returns:
+

an Info object having parameter values, and a run_mode string

+
+
Return type:
+

Tuple(Info, str)

+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse._main.html b/manual/v3.0.0/api/odatse._main.html new file mode 100644 index 00000000..2dc16ce2 --- /dev/null +++ b/manual/v3.0.0/api/odatse._main.html @@ -0,0 +1,134 @@ + + + + + + + + + odatse._main module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse._main module

+
+
+odatse._main.main()[source]
+

Main function to run the data-analysis software for quantum beam diffraction experiments +on 2D material structures. It parses command-line arguments, loads the input file, +selects the appropriate algorithm and solver, and executes the analysis.

+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse._runner.html b/manual/v3.0.0/api/odatse._runner.html new file mode 100644 index 00000000..31c26673 --- /dev/null +++ b/manual/v3.0.0/api/odatse._runner.html @@ -0,0 +1,126 @@ + + + + + + + + + odatse._runner module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse._runner module

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm._algorithm.html b/manual/v3.0.0/api/odatse.algorithm._algorithm.html new file mode 100644 index 00000000..18dfa813 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm._algorithm.html @@ -0,0 +1,317 @@ + + + + + + + + + odatse.algorithm._algorithm module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm._algorithm module

+
+
+class odatse.algorithm._algorithm.AlgorithmBase(info: Info, runner: Runner | None = None, run_mode: str = 'initial')[source]
+

Bases: object

+

Base class for algorithms, providing common functionality and structure.

+

Initialize the algorithm with the given information and runner.

+
+
Parameters:
+
    +

  • info (Info) – Information object containing algorithm and base parameters.

    • +

  • runner (Runner (optional)) – Optional runner object to execute the algorithm.

    • +

  • run_mode (str) – Mode in which the algorithm should run.

    • +
+
+
+
+
+abstract __init__(info: Info, runner: Runner | None = None, run_mode: str = 'initial') → None[source]
+

Initialize the algorithm with the given information and runner.

+
+
Parameters:
+
    +

  • info (Info) – Information object containing algorithm and base parameters.

    • +

  • runner (Runner (optional)) – Optional runner object to execute the algorithm.

    • +

  • run_mode (str) – Mode in which the algorithm should run.

    • +
+
+
+
+ +
+
+__init_rng(info: Info) → None
+

Initialize the random number generator.

+
+
Parameters:
+

info (Info) – Information object containing algorithm parameters.

+
+
+
+ +
+
+_check_parameters(param=None)[source]
+

Check the parameters of the algorithm against previous parameters.

+
+
Parameters:
+

(optional) (param) – Previous parameters to check against.

+
+
+
+ +
+
+_load_data(filename='state.pickle') → Dict[source]
+

Load data from a file.

+
+
Parameters:
+

filename – Name of the file to load the data from.

+
+
Returns:
+

Dictionary containing the loaded data.

+
+
Return type:
+

Dict

+
+
+
+ +
+
+abstract _post() → Dict[source]
+

Abstract method to be implemented by subclasses for post-processing steps.

+
+ +
+
+abstract _prepare() → None[source]
+

Abstract method to be implemented by subclasses for preparation steps.

+
+ +
+
+abstract _run() → None[source]
+

Abstract method to be implemented by subclasses for running steps.

+
+ +
+
+_save_data(data, filename='state.pickle', ngen=3) → None[source]
+

Save data to a file with versioning.

+
+
Parameters:
+
    +

  • data – Data to be saved.

    • +

  • filename – Name of the file to save the data.

    • +

  • ngen (int, default: 3) – Number of generations for versioning.

    • +
+
+
+
+ +
+
+_show_parameters()[source]
+

Show the parameters of the algorithm.

+
+ +
+
+main()[source]
+

Main method to execute the algorithm.

+
+ +
+
+post() → Dict[source]
+

Perform post-processing after the algorithm has run.

+
+
Returns:
+

Dictionary containing post-processing results.

+
+
Return type:
+

Dict

+
+
+
+ +
+
+prepare() → None[source]
+

Prepare the algorithm for execution.

+
+ +
+
+run() → None[source]
+

Run the algorithm.

+
+ +
+
+set_runner(runner: Runner) → None[source]
+

Set the runner for the algorithm.

+
+
Parameters:
+

runner (Runner) – Runner object to execute the algorithm.

+
+
+
+ +
+
+write_timer(filename: Path)[source]
+

Write the timing information to a file.

+
+
Parameters:
+

filename (Path) – Path to the file where timing information will be written.

+
+
+
+ +
+ +
+
+class odatse.algorithm._algorithm.AlgorithmStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
+

Bases: IntEnum

+

Enumeration for the status of the algorithm.

+
+ +
+
+odatse.algorithm._algorithm.flatten_dict(d, parent_key='', separator='.')[source]
+

Flatten a nested dictionary.

+
+
Parameters:
+
    +

  • d – Dictionary to flatten.

    • +

  • parent_key (str, default : "") – Key for the parent dictionary.

    • +

  • separator (str, default : ".") – Separator to use between keys.

    • +
+
+
Returns:
+

Flattened dictionary.

+
+
Return type:
+

dict

+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.bayes.html b/manual/v3.0.0/api/odatse.algorithm.bayes.html new file mode 100644 index 00000000..2432eed9 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.bayes.html @@ -0,0 +1,341 @@ + + + + + + + + + odatse.algorithm.bayes module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm.bayes module

+
+
+class odatse.algorithm.bayes.Algorithm(info: Info, runner: Runner = None, domain=None, run_mode: str = 'initial')[source]
+

Bases: AlgorithmBase

+

A class to represent the Bayesian optimization algorithm.

+
+
+mesh_list
+

The mesh grid list.

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+label_list
+

The list of labels.

+
+
Type:
+

List[str]

+
+
+
+ +
+
+random_max_num_probes
+

The maximum number of random probes.

+
+
Type:
+

int

+
+
+
+ +
+
+bayes_max_num_probes
+

The maximum number of Bayesian probes.

+
+
Type:
+

int

+
+
+
+ +
+
+score
+

The scoring method.

+
+
Type:
+

str

+
+
+
+ +
+
+interval
+

The interval for Bayesian optimization.

+
+
Type:
+

int

+
+
+
+ +
+
+num_rand_basis
+

The number of random basis.

+
+
Type:
+

int

+
+
+
+ +
+
+xopt
+

The optimal solution.

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+best_fx
+

The list of best function values.

+
+
Type:
+

List[float]

+
+
+
+ +
+
+best_action
+

The list of best actions.

+
+
Type:
+

List[int]

+
+
+
+ +
+
+fx_list
+

The list of function values.

+
+
Type:
+

List[float]

+
+
+
+ +
+
+param_list
+

The list of parameters.

+
+
Type:
+

List[np.ndarray]

+
+
+
+ +

Constructs all the necessary attributes for the Algorithm object.

+
+
Parameters:
+
    +

  • info (odatse.Info) – The information object.

    • +

  • runner (odatse.Runner, optional) – The runner object (default is None).

    • +

  • domain (optional) – The domain object (default is None).

    • +

  • run_mode (str, optional) – The run mode (default is “initial”).

    • +
+
+
+
+
+__init__(info: Info, runner: Runner = None, domain=None, run_mode: str = 'initial') → None[source]
+

Constructs all the necessary attributes for the Algorithm object.

+
+
Parameters:
+
    +

  • info (odatse.Info) – The information object.

    • +

  • runner (odatse.Runner, optional) – The runner object (default is None).

    • +

  • domain (optional) – The domain object (default is None).

    • +

  • run_mode (str, optional) – The run mode (default is “initial”).

    • +
+
+
+
+ +
+
+_initialize()[source]
+

Initializes the algorithm parameters and timers.

+
+ +
+
+_load_state(filename, mode='resume', restore_rng=True)[source]
+

Loads the state of the algorithm from a file.

+
+
Parameters:
+
    +

  • filename (str) – The name of the file to load the state from.

    • +

  • mode (str, optional) – The mode to load the state (default is “resume”).

    • +

  • restore_rng (bool, optional) – Whether to restore the random number generator state (default is True).

    • +
+
+
+
+ +
+
+_post() → None[source]
+

Finalizes the algorithm execution and writes the results to a file.

+
+ +
+
+_prepare() → None[source]
+

Prepares the algorithm for execution.

+
+ +
+
+_run() → None[source]
+

Runs the Bayesian optimization process.

+
+ +
+
+_save_state(filename)[source]
+

Saves the current state of the algorithm to a file.

+
+
Parameters:
+

filename (str) – The name of the file to save the state.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.exchange.html b/manual/v3.0.0/api/odatse.algorithm.exchange.html new file mode 100644 index 00000000..90dbb6e8 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.exchange.html @@ -0,0 +1,378 @@ + + + + + + + + + odatse.algorithm.exchange module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm.exchange module

+
+
+class odatse.algorithm.exchange.Algorithm(info: Info, runner: Runner = None, run_mode: str = 'initial')[source]
+

Bases: AlgorithmBase

+

Replica Exchange Monte Carlo

+
+
+x
+

current configuration

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+inode
+

current configuration index (discrete parameter space)

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+fx
+

current “Energy”

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+Tindex
+

current “Temperature” index

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+istep
+

current step (or, the number of calculated energies)

+
+
Type:
+

int

+
+
+
+ +
+
+best_x
+

best configuration

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+best_fx
+

best “Energy”

+
+
Type:
+

float

+
+
+
+ +
+
+best_istep
+

index of best configuration

+
+
Type:
+

int

+
+
+
+ +
+
+nreplica
+

The number of replicas (= the number of procs)

+
+
Type:
+

int

+
+
+
+ +
+
+T2rep
+

Mapping from temperature index to replica index

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+rep2T
+

Reverse mapping from replica index to temperature index

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+exchange_direction
+

Parity of exchange direction

+
+
Type:
+

bool

+
+
+
+ +

Initialize the Algorithm class.

+
+
Parameters:
+
    +

  • info (odatse.Info) – Information object containing algorithm parameters.

    • +

  • runner (odatse.Runner, optional) – Runner object for executing the algorithm.

    • +

  • run_mode (str, optional) – Mode to run the algorithm in, by default “initial”.

    • +
+
+
+
+
+__exchange_multi_walker(direction: bool) → None
+

Exchange temperatures for multiple walkers.

+
+
Parameters:
+

direction (bool) – Direction of the exchange.

+
+
+
+ +
+
+__exchange_single_walker(direction: bool) → None
+

Exchange temperatures for a single walker.

+
+
Parameters:
+

direction (bool) – Direction of the exchange.

+
+
+
+ +
+
+__init__(info: Info, runner: Runner = None, run_mode: str = 'initial') → None[source]
+

Initialize the Algorithm class.

+
+
Parameters:
+
    +

  • info (odatse.Info) – Information object containing algorithm parameters.

    • +

  • runner (odatse.Runner, optional) – Runner object for executing the algorithm.

    • +

  • run_mode (str, optional) – Mode to run the algorithm in, by default “initial”.

    • +
+
+
+
+ +
+
+_exchange(direction: bool) → None[source]
+

Try to exchange temperatures.

+
+
Parameters:
+

direction (bool) – Direction of the exchange.

+
+
+
+ +
+
+_initialize() → None[source]
+

Initialize the algorithm parameters and state.

+
+ +
+
+_load_state(filename, mode='resume', restore_rng=True)[source]
+

Load the state of the algorithm from a file.

+
+
Parameters:
+
    +

  • filename (str) – The name of the file to load the state from.

    • +

  • mode (str, optional) – The mode to load the state in, by default “resume”.

    • +

  • restore_rng (bool, optional) – Whether to restore the random number generator state, by default True.

    • +
+
+
+
+ +
+
+_post() → None[source]
+

Post-process the results of the algorithm.

+
+ +
+
+_prepare() → None[source]
+

Prepare the algorithm for execution.

+
+ +
+
+_print_info() → None[source]
+

Print information about the algorithm.

+
+ +
+
+_run() → None[source]
+

Run the algorithm.

+
+ +
+
+_save_state(filename) → None[source]
+

Save the current state of the algorithm.

+
+
Parameters:
+

filename (str) – The name of the file to save the state to.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.html b/manual/v3.0.0/api/odatse.algorithm.html new file mode 100644 index 00000000..b2a61f40 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.html @@ -0,0 +1,155 @@ + + + + + + + + + odatse.algorithm package — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm package

+
+
+odatse.algorithm.choose_algorithm(name)[source]
+

Search for algorithm module by name

+
+
Parameters:
+

name (str) – name of the algorithm

+
+
Returns:
+

algorithm module

+
+
Return type:
+

module

+
+
+
+ +
+

Submodules

+
+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.mapper_mpi.html b/manual/v3.0.0/api/odatse.algorithm.mapper_mpi.html new file mode 100644 index 00000000..b1aeb5b0 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.mapper_mpi.html @@ -0,0 +1,223 @@ + + + + + + + + + odatse.algorithm.mapper_mpi module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm.mapper_mpi module

+
+
+class odatse.algorithm.mapper_mpi.Algorithm(info: Info, runner: Runner = None, domain=None, run_mode: str = 'initial')[source]
+

Bases: AlgorithmBase

+

Algorithm class for data analysis of quantum beam diffraction experiments. +Inherits from odatse.algorithm.AlgorithmBase.

+

Initialize the Algorithm instance.

+
+
Parameters:
+
    +

  • info (Info) – Information object containing algorithm parameters.

    • +

  • runner (Runner) – Optional runner object for submitting tasks.

    • +

  • domain – Optional domain object, defaults to MeshGrid.

    • +

  • run_mode (str) – Mode to run the algorithm, defaults to “initial”.

    • +
+
+
+
+
+__init__(info: Info, runner: Runner = None, domain=None, run_mode: str = 'initial') → None[source]
+

Initialize the Algorithm instance.

+
+
Parameters:
+
    +

  • info (Info) – Information object containing algorithm parameters.

    • +

  • runner (Runner) – Optional runner object for submitting tasks.

    • +

  • domain – Optional domain object, defaults to MeshGrid.

    • +

  • run_mode (str) – Mode to run the algorithm, defaults to “initial”.

    • +
+
+
+
+ +
+
+_initialize() → None[source]
+

Initialize the algorithm parameters and timer.

+
+ +
+
+_load_state(filename, restore_rng=True)[source]
+

Load the state of the algorithm from a file.

+
+
Parameters:
+
    +

  • filename – The name of the file to load the state from.

    • +

  • restore_rng (bool) – Whether to restore the random number generator state.

    • +
+
+
+
+ +
+
+_output_results()[source]
+

Output the results to the colormap file.

+
+ +
+
+_post() → Dict[source]
+

Post-process the results and gather data from all MPI ranks.

+
+
Returns:
+

Dictionary of results.

+
+
Return type:
+

Dict

+
+
+
+ +
+
+_prepare() → None[source]
+

Prepare the algorithm (no operation).

+
+ +
+
+_run() → None[source]
+

Execute the main algorithm process.

+
+ +
+
+_save_state(filename) → None[source]
+

Save the current state of the algorithm to a file.

+
+
Parameters:
+

filename – The name of the file to save the state to.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.min_search.html b/manual/v3.0.0/api/odatse.algorithm.min_search.html new file mode 100644 index 00000000..ce8336e4 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.min_search.html @@ -0,0 +1,183 @@ + + + + + + + + + odatse.algorithm.min_search module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ + + + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.montecarlo.html b/manual/v3.0.0/api/odatse.algorithm.montecarlo.html new file mode 100644 index 00000000..f3cdc834 --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.montecarlo.html @@ -0,0 +1,427 @@ + + + + + + + + + odatse.algorithm.montecarlo module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm.montecarlo module

+
+
+class odatse.algorithm.montecarlo.AlgorithmBase(info: Info, runner: Runner = None, domain=None, nwalkers: int = 1, run_mode: str = 'initial')[source]
+

Bases: AlgorithmBase

+

Base of Monte Carlo

+
+
+nwalkers
+

the number of walkers (per one process)

+
+
Type:
+

int

+
+
+
+ +
+
+x
+

current configurations +(NxD array, N is the number of walkers and D is the dimension)

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+fx
+

current “Energy”s

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+istep
+

current step (or, the number of calculated energies)

+
+
Type:
+

int

+
+
+
+ +
+
+best_x
+

best configuration

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+best_fx
+

best “Energy”

+
+
Type:
+

float

+
+
+
+ +
+
+best_istep
+

index of best configuration (step)

+
+
Type:
+

int

+
+
+
+ +
+
+best_iwalker
+

index of best configuration (walker)

+
+
Type:
+

int

+
+
+
+ +
+
+comm
+

MPI communicator

+
+
Type:
+

MPI.comm

+
+
+
+ +
+
+rank
+

MPI rank

+
+
Type:
+

int

+
+
+
+ +
+
+Ts
+

List of temperatures

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+Tindex
+

Temperature index

+
+
Type:
+

np.ndarray

+
+
+
+ +

Initialize the AlgorithmBase class.

+
+
Parameters:
+
    +

  • info (odatse.Info) – Information object containing algorithm parameters.

    • +

  • runner (odatse.Runner, optional) – Runner object for executing the algorithm (default is None).

    • +

  • domain (optional) – Domain object defining the problem space (default is None).

    • +

  • nwalkers (int, optional) – Number of walkers (default is 1).

    • +

  • run_mode (str, optional) – Mode of the run, e.g., “initial” (default is “initial”).

    • +
+
+
+
+
+__init__(info: Info, runner: Runner = None, domain=None, nwalkers: int = 1, run_mode: str = 'initial') → None[source]
+

Initialize the AlgorithmBase class.

+
+
Parameters:
+
    +

  • info (odatse.Info) – Information object containing algorithm parameters.

    • +

  • runner (odatse.Runner, optional) – Runner object for executing the algorithm (default is None).

    • +

  • domain (optional) – Domain object defining the problem space (default is None).

    • +

  • nwalkers (int, optional) – Number of walkers (default is 1).

    • +

  • run_mode (str, optional) – Mode of the run, e.g., “initial” (default is “initial”).

    • +
+
+
+
+ +
+
+_evaluate(in_range: ndarray = None) → ndarray[source]
+

Evaluate the current “Energy”s.

+

This method overwrites self.fx with the result.

+
+
Parameters:
+

in_range (np.ndarray, optional) – Array indicating whether each walker is within the valid range (default is None).

+
+
Returns:
+

Array of evaluated energies for the current configurations.

+
+
Return type:
+

np.ndarray

+
+
+
+ +
+
+_initialize()[source]
+

Initialize the algorithm state.

+

This method sets up the initial state of the algorithm, including the +positions and energies of the walkers, and resets the counters for +accepted and trial steps.

+
+ +
+
+_setup_neighbour(info_param)[source]
+

Set up the neighbor list for the discrete problem.

+
+
Parameters:
+

info_param (dict) – Dictionary containing algorithm parameters, including the path to the neighbor list file.

+
+
Raises:
+
    +

  • ValueError – If the neighbor list path is not specified in the parameters.

    • +

  • RuntimeError – If the transition graph made from the neighbor list is not connected or not bidirectional.

    • +
+
+
+
+ +
+
+_write_result(fp, extra_info_to_write: List | Tuple = None) → None[source]
+

Write the result of the current step to the file.

+
+
Parameters:
+
    +

  • fp (TextIO) – File pointer to the result file.

    • +

  • extra_info_to_write (Union[List, Tuple], optional) – Additional information to write for each walker (default is None).

    • +
+
+
+
+ +
+
+_write_result_header(fp, extra_names=None) → None[source]
+

Write the header for the result file.

+
+
Parameters:
+
    +

  • fp (TextIO) – File pointer to the result file.

    • +

  • extra_names (list of str, optional) – Additional column names to include in the header.

    • +
+
+
+
+ +
+
+local_update(beta: float | ndarray, file_trial: TextIO, file_result: TextIO, extra_info_to_write: List | Tuple = None)[source]
+

one step of Monte Carlo

+
+
Parameters:
+
    +

  • beta (np.ndarray) – inverse temperature for each walker

    • +

  • file_trial (TextIO) – log file for all trial points

    • +

  • file_result (TextIO) – log file for all generated samples

    • +

  • extra_info_to_write (List of np.ndarray or tuple of np.ndarray) – extra information to write

    • +
+
+
+
+ +
+
+propose(current: ndarray) → ndarray[source]
+

Propose the next candidate positions for the walkers.

+
+
Parameters:
+

current (np.ndarray) – Current positions of the walkers.

+
+
Returns:
+

proposed – Proposed new positions for the walkers.

+
+
Return type:
+

np.ndarray

+
+
+
+ +
+ +
+
+odatse.algorithm.montecarlo.read_Ts(info: dict, numT: int = None) → Tuple[bool, ndarray][source]
+

Read temperature or inverse-temperature values from the provided info dictionary.

+
+
Parameters:
+
    +

  • info (dict) – Dictionary containing temperature or inverse-temperature parameters.

    • +

  • numT (int, optional) – Number of temperature or inverse-temperature values to generate (default is None).

    • +
+
+
Returns:
+

    +

  • as_beta (bool) – True if using inverse-temperature, False if using temperature.

    • +

  • betas (np.ndarray) – Sequence of inverse-temperature values.

    • +
+

+
+
Raises:
+
    +

  • ValueError – If numT is not specified, or if both Tmin/Tmax and bmin/bmax are defined, or if neither are defined, + or if bmin/bmax or Tmin/Tmax values are invalid.

    • +

  • RuntimeError – If the mode is unknown (neither set_T nor set_b).

    • +
+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.algorithm.pamc.html b/manual/v3.0.0/api/odatse.algorithm.pamc.html new file mode 100644 index 00000000..09ecc50f --- /dev/null +++ b/manual/v3.0.0/api/odatse.algorithm.pamc.html @@ -0,0 +1,473 @@ + + + + + + + + + odatse.algorithm.pamc module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.algorithm.pamc module

+
+
+class odatse.algorithm.pamc.Algorithm(info: Info, runner: Runner = None, run_mode: str = 'initial')[source]
+

Bases: AlgorithmBase

+

Population annealing Monte Carlo

+
+
+x
+

current configuration

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+fx
+

current “Energy”

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+logweights
+

current logarithm of weights (Neal-Jarzynski factor)

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+istep
+

current step (or, the number of calculated energies)

+
+
Type:
+

int

+
+
+
+ +
+
+best_x
+

best configuration

+
+
Type:
+

np.ndarray

+
+
+
+ +
+
+best_fx
+

best “Energy”

+
+
Type:
+

float

+
+
+
+ +
+
+best_istep
+

index of best configuration

+
+
Type:
+

int

+
+
+
+ +
+
+comm
+

MPI communicator

+
+
Type:
+

MPI.comm

+
+
+
+ +
+
+nreplica
+

The number of replicas (= the number of procs)

+
+
Type:
+

int

+
+
+
+ +
+
+rank
+

MPI rank

+
+
Type:
+

int

+
+
+
+ +
+
+betas
+

List of inverse temperatures

+
+
Type:
+

list

+
+
+
+ +
+
+Tindex
+

Temperature index

+
+
Type:
+

int

+
+
+
+ +

Initialize the Algorithm class.

+
+
Parameters:
+
    +

  • info (odatse.Info) – Information object containing algorithm parameters.

    • +

  • runner (odatse.Runner, optional) – Runner object for executing the algorithm, by default None.

    • +

  • run_mode (str, optional) – Mode in which to run the algorithm, by default “initial”.

    • +
+
+
+
+
+__init__(info: Info, runner: Runner = None, run_mode: str = 'initial') → None[source]
+

Initialize the Algorithm class.

+
+
Parameters:
+
    +

  • info (odatse.Info) – Information object containing algorithm parameters.

    • +

  • runner (odatse.Runner, optional) – Runner object for executing the algorithm, by default None.

    • +

  • run_mode (str, optional) – Mode in which to run the algorithm, by default “initial”.

    • +
+
+
+
+ +
+
+_find_scheduling(info_pamc) → int[source]
+

Determine the scheduling for the algorithm based on the provided parameters.

+
+
Parameters:
+

info_pamc (dict) – Dictionary containing the parameters for the PAMC algorithm.

+
+
Returns:
+

The number of temperature steps (numT) determined from the input parameters.

+
+
Return type:
+

int

+
+
+
+ +
+
+_gather_information(numT: int = None) → Dict[str, ndarray][source]
+

Gather status information of each process

+
+
Parameters:
+

numT (int) – size of dataset

+
+
Returns:
+

res – key-value corresponding is the following

+
    +
  • +
    fxs
      +

    • objective function of each walker over all processes

      • +
    +
    +
    +
    • +
  • +
    logweights
      +

    • log of weights

      • +
    +
    +
    +
    • +
  • +
    ns
      +

    • number of walkers in each process

      • +
    +
    +
    +
    • +
  • +
    ancestors
      +

    • ancestor (origin) of each walker

      • +
    +
    +
    +
    • +
  • +
    acceptance ratio
      +

    • acceptance_ratio for each temperature

      • +
    +
    +
    +
    • +
+

+
+
Return type:
+

Dict[str, np.ndarray]

+
+
+
+ +
+
+_initialize() → None[source]
+

Initialize the algorithm state.

+

This method sets up the initial state of the algorithm, including the +positions and energies of the walkers, and resets the counters for +accepted and trial steps.

+
+ +
+
+_load_state(filename, mode='resume', restore_rng=True)[source]
+

Load the saved state of the algorithm from a file.

+
+
Parameters:
+
    +

  • filename (str) – The name of the file from which the state will be loaded.

    • +

  • mode (str, optional) – The mode in which to load the state. Can be “resume” or “continue”, by default “resume”.

    • +

  • restore_rng (bool, optional) – Whether to restore the random number generator state, by default True.

    • +
+
+
+
+ +
+
+_post() → None[source]
+

Post-processing after the algorithm execution.

+

This method consolidates the results from different temperature steps +into single files for ‘result’ and ‘trial’. It also gathers the best +results from all processes and writes them to ‘best_result.txt’.

+
+ +
+
+_prepare() → None[source]
+

Prepare the algorithm for execution.

+

This method initializes the timers for the ‘submit’ and ‘resampling’ phases +of the algorithm run.

+
+ +
+
+_resample() → None[source]
+

Perform the resampling of walkers.

+

This method gathers information, saves statistical data, and performs resampling +using either fixed or varied weights. The method ensures that the algorithm +maintains a balanced set of walkers across different temperature steps.

+
+ +
+
+_resample_fixed(weights: ndarray) → None[source]
+

Perform resampling with fixed weights.

+

This method resamples the walkers based on the provided weights and updates +the state of the algorithm accordingly.

+
+
Parameters:
+

weights (np.ndarray) – Array of weights for resampling.

+
+
+
+ +
+
+_resample_varied(weights: ndarray, offset: int) → None[source]
+

Perform resampling with varied weights.

+

This method resamples the walkers based on the provided weights and updates +the state of the algorithm accordingly.

+
+
Parameters:
+
    +

  • weights (np.ndarray) – Array of weights for resampling.

    • +

  • offset (int) – Offset for the weights array.

    • +
+
+
+
+ +
+
+_run() → None[source]
+

Abstract method to be implemented by subclasses for running steps.

+
+ +
+
+_save_state(filename) → None[source]
+

Save the current state of the algorithm to a file.

+
+
Parameters:
+

filename (str) – The name of the file where the state will be saved.

+
+
+
+ +
+
+_save_stats(info: Dict[str, ndarray]) → None[source]
+

Save statistical information from the algorithm run.

+
+
Parameters:
+

info (Dict[str, np.ndarray]) – Dictionary containing the following keys: +- fxs: Objective function of each walker over all processes. +- logweights: Logarithm of weights. +- ns: Number of walkers in each process. +- ancestors: Ancestor (origin) of each walker. +- acceptance ratio: Acceptance ratio for each temperature.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.domain._domain.html b/manual/v3.0.0/api/odatse.domain._domain.html new file mode 100644 index 00000000..249a6c99 --- /dev/null +++ b/manual/v3.0.0/api/odatse.domain._domain.html @@ -0,0 +1,193 @@ + + + + + + + + + odatse.domain._domain module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.domain._domain module

+
+
+class odatse.domain._domain.DomainBase(info: Info = None)[source]
+

Bases: object

+

Base class for domain management in the 2DMAT software.

+
+
+root_dir
+

The root directory for the domain.

+
+
Type:
+

Path

+
+
+
+ +
+
+output_dir
+

The output directory for the domain.

+
+
Type:
+

Path

+
+
+
+ +
+
+mpisize
+

The size of the MPI communicator.

+
+
Type:
+

int

+
+
+
+ +
+
+mpirank
+

The rank of the MPI process.

+
+
Type:
+

int

+
+
+
+ +

Initializes the DomainBase instance.

+
+
Parameters:
+

info (Info, optional) – An instance of odatse.Info containing base directory information.

+
+
+
+
+__init__(info: Info = None)[source]
+

Initializes the DomainBase instance.

+
+
Parameters:
+

info (Info, optional) – An instance of odatse.Info containing base directory information.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.domain.html b/manual/v3.0.0/api/odatse.domain.html new file mode 100644 index 00000000..5a487ef8 --- /dev/null +++ b/manual/v3.0.0/api/odatse.domain.html @@ -0,0 +1,134 @@ + + + + + + + + + odatse.domain package — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.domain package

+
+

Submodules

+
+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.domain.meshgrid.html b/manual/v3.0.0/api/odatse.domain.meshgrid.html new file mode 100644 index 00000000..d091f860 --- /dev/null +++ b/manual/v3.0.0/api/odatse.domain.meshgrid.html @@ -0,0 +1,242 @@ + + + + + + + + + odatse.domain.meshgrid module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.domain.meshgrid module

+
+
+class odatse.domain.meshgrid.MeshGrid(info: Info = None, *, param: Dict[str, Any] = None)[source]
+

Bases: DomainBase

+

MeshGrid class for handling grid data for quantum beam diffraction experiments.

+

Initialize the MeshGrid object.

+
+
Parameters:
+
    +

  • info (Info, optional) – Information object containing algorithm parameters.

    • +

  • param (dict, optional) – Dictionary containing parameters for setting up the grid.

    • +
+
+
+
+
+__init__(info: Info = None, *, param: Dict[str, Any] = None)[source]
+

Initialize the MeshGrid object.

+
+
Parameters:
+
    +

  • info (Info, optional) – Information object containing algorithm parameters.

    • +

  • param (dict, optional) – Dictionary containing parameters for setting up the grid.

    • +
+
+
+
+ +
+
+_setup(info_param)[source]
+

Setup the grid based on provided parameters.

+
+
Parameters:
+

info_param – Dictionary containing parameters for setting up the grid.

+
+
+
+ +
+
+_setup_from_file(info_param)[source]
+

Setup the grid from a file.

+
+
Parameters:
+

info_param – Dictionary containing parameters for setting up the grid.

+
+
+
+ +
+
+_setup_grid(info_param)[source]
+

Setup the grid based on min, max, and num lists.

+
+
Parameters:
+

info_param – Dictionary containing parameters for setting up the grid.

+
+
+
+ +
+
+do_split()[source]
+

Split the grid data among MPI processes.

+
+ +
+
+classmethod from_dict(param)[source]
+

Create a MeshGrid object from a dictionary of parameters.

+
+
Parameters:
+

param – Dictionary containing parameters for setting up the grid.

+
+
Returns:
+

a MeshGrid object.

+
+
Return type:
+

MeshGrid

+
+
+
+ +
+
+classmethod from_file(mesh_path)[source]
+

Create a MeshGrid object from a file.

+
+
Parameters:
+

mesh_path – Path to the file containing the grid data.

+
+
Returns:
+

a MeshGrid object.

+
+
Return type:
+

MeshGrid

+
+
+
+ +
+
+store_file(store_path, *, header='')[source]
+

Store the grid data to a file.

+
+
Parameters:
+
    +

  • store_path – Path to the file where the grid data will be stored.

    • +

  • header – Header to be included in the file.

    • +
+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.domain.region.html b/manual/v3.0.0/api/odatse.domain.region.html new file mode 100644 index 00000000..84c05551 --- /dev/null +++ b/manual/v3.0.0/api/odatse.domain.region.html @@ -0,0 +1,240 @@ + + + + + + + + + odatse.domain.region module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.domain.region module

+
+
+class odatse.domain.region.Region(info: Info = None, *, param: Dict[str, Any] = None)[source]
+

Bases: DomainBase

+

A class to represent a region in the domain.

+
+
+min_list
+

Minimum values for each dimension.

+
+
Type:
+

np.array

+
+
+
+ +
+
+max_list
+

Maximum values for each dimension.

+
+
Type:
+

np.array

+
+
+
+ +
+
+unit_list
+

Unit values for each dimension.

+
+
Type:
+

np.array

+
+
+
+ +
+
+initial_list
+

Initial values for each dimension.

+
+
Type:
+

np.array

+
+
+
+ +

Initialize the Region object.

+
+
Parameters:
+
    +

  • info (odatse.Info, optional) – Information object containing algorithm parameters.

    • +

  • param (dict, optional) – Dictionary containing algorithm parameters.

    • +
+
+
+
+
+__init__(info: Info = None, *, param: Dict[str, Any] = None)[source]
+

Initialize the Region object.

+
+
Parameters:
+
    +

  • info (odatse.Info, optional) – Information object containing algorithm parameters.

    • +

  • param (dict, optional) – Dictionary containing algorithm parameters.

    • +
+
+
+
+ +
+
+_init_random(rng=<module 'numpy.random' from '/opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/numpy/random/__init__.py'>, limitation=<odatse.util.limitation.Unlimited object>, max_count=100)[source]
+

Initialize the region with random values within the specified limits.

+
+
Parameters:
+
    +

  • rng (numpy.random, optional) – Random number generator.

    • +

  • limitation (odatse.util.limitation, optional) – Limitation object to judge the validity of the values.

    • +

  • max_count (int, optional) – Maximum number of trials to generate valid values.

    • +
+
+
+
+ +
+
+_setup(info_param)[source]
+

Setup the region with the given parameters.

+
+
Parameters:
+

info_param (dict) – Dictionary containing the parameters for the region.

+
+
+
+ +
+
+initialize(rng=<module 'numpy.random' from '/opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/numpy/random/__init__.py'>, limitation=<odatse.util.limitation.Unlimited object>, num_walkers: int = 1)[source]
+

Initialize the region with random values or predefined initial values.

+
+
Parameters:
+
    +

  • rng (numpy.random, optional) – Random number generator.

    • +

  • limitation (odatse.util.limitation, optional) – Limitation object to judge the validity of the values.

    • +

  • num_walkers (int, optional) – Number of walkers to initialize.

    • +
+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.exception.html b/manual/v3.0.0/api/odatse.exception.html new file mode 100644 index 00000000..adc808e7 --- /dev/null +++ b/manual/v3.0.0/api/odatse.exception.html @@ -0,0 +1,145 @@ + + + + + + + + + odatse.exception module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.exception module

+
+
+exception odatse.exception.Error[source]
+

Bases: Exception

+

Base class of exceptions in odatse

+
+ +
+
+exception odatse.exception.InputError(message: str)[source]
+

Bases: Error

+

Exception raised for errors in inputs

+
+
Parameters:
+

message (str) – explanation

+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.html b/manual/v3.0.0/api/odatse.html new file mode 100644 index 00000000..695f89a6 --- /dev/null +++ b/manual/v3.0.0/api/odatse.html @@ -0,0 +1,155 @@ + + + + + + + + + odatse package — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.mpi.html b/manual/v3.0.0/api/odatse.mpi.html new file mode 100644 index 00000000..6e751a50 --- /dev/null +++ b/manual/v3.0.0/api/odatse.mpi.html @@ -0,0 +1,124 @@ + + + + + + + + + odatse.mpi module — ODAT-SE API documentation + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.mpi module

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.solver._solver.html b/manual/v3.0.0/api/odatse.solver._solver.html new file mode 100644 index 00000000..66de6583 --- /dev/null +++ b/manual/v3.0.0/api/odatse.solver._solver.html @@ -0,0 +1,182 @@ + + + + + + + + + odatse.solver._solver module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.solver._solver module

+
+
+class odatse.solver._solver.SolverBase(info: Info)[source]
+

Bases: object

+

Abstract base class for solvers in the 2DMAT software.

+

Initialize the solver with the given information.

+
+
Parameters:
+

info (Info) – Information object containing configuration details.

+
+
+
+
+abstract __init__(info: Info) → None[source]
+

Initialize the solver with the given information.

+
+
Parameters:
+

info (Info) – Information object containing configuration details.

+
+
+
+ +
+
+abstract evaluate(x: ndarray, arg: Tuple = (), nprocs: int = 1, nthreads: int = 1) → None[source]
+

Evaluate the solver with the given parameters.

+
+
Parameters:
+
    +

  • x (np.ndarray) – Input data array.

    • +

  • arg (Tuple, optional) – Additional arguments for evaluation. Defaults to ().

    • +

  • nprocs (nt, optional) – Number of processes to use. Defaults to 1.

    • +

  • nthreads (int, optional) – Number of threads to use. Defaults to 1.

    • +
+
+
Raises:
+

NotImplementedError – This method should be implemented by subclasses.

+
+
+
+ +
+
+property name: str
+

Get the name of the solver.

+
+
Returns:
+

The name of the solver.

+
+
Return type:
+

str

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.solver.analytical.html b/manual/v3.0.0/api/odatse.solver.analytical.html new file mode 100644 index 00000000..406f5d03 --- /dev/null +++ b/manual/v3.0.0/api/odatse.solver.analytical.html @@ -0,0 +1,270 @@ + + + + + + + + + odatse.solver.analytical module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.solver.analytical module

+
+
+class odatse.solver.analytical.Solver(info: Info)[source]
+

Bases: Solver

+

Function Solver with pre-defined benchmark functions

+

Initialize the solver.

+
+
Parameters:
+

info (Info) – Information object containing solver configuration.

+
+
+
+
+__init__(info: Info) → None[source]
+

Initialize the solver.

+
+
Parameters:
+

info (Info) – Information object containing solver configuration.

+
+
+
+ +
+ +
+
+odatse.solver.analytical.ackley(xs: ndarray) → float[source]
+

Ackley’s function in arbitrary dimension

+
+
Parameters:
+

xs (np.ndarray) – Input array.

+
+
Returns:
+

The calculated value of Ackley’s function.

+
+
Return type:
+

float

+
+
+

Notes

+

It has one global minimum f(xs)=0 at xs=[0,0,…,0]. +It has many local minima.

+
+ +
+
+odatse.solver.analytical.himmelblau(xs: ndarray) → float[source]
+

Himmelblau’s function.

+
+
Parameters:
+

xs (np.ndarray) – Input array of shape (2,).

+
+
Returns:
+

The calculated value of Himmelblau’s function.

+
+
Return type:
+

float

+
+
+

Notes

+

It has four global minima f(xs) = 0 at +xs=[3,2], [-2.805118…, 3.131312…], [-3.779310…, -3.2831860], and [3.584428…, -1.848126…].

+
+ +
+
+odatse.solver.analytical.linear_regression_test(xs: ndarray) → float[source]
+

Negative log likelihood of linear regression with Gaussian noise N(0,sigma)

+

y = ax + b

+

trained by xdata = [1, 2, 3, 4, 5, 6] and ydata = [1, 3, 2, 4, 3, 5].

+

Model parameters (a, b, sigma) are corresponding to xs as the following, +a = xs[0], b = xs[1], log(sigma**2) = xs[2]

+

It has a global minimum f(xs) = 1.005071.. at +xs = [0.628571…, 0.8, -0.664976…].

+
+
Parameters:
+

xs (np.ndarray) – Input array of model parameters.

+
+
Returns:
+

The negative log likelihood of the linear regression model.

+
+
Return type:
+

float

+
+
+
+ +
+
+odatse.solver.analytical.quadratics(xs: ndarray) → float[source]
+

Quadratic (sphere) function.

+
+
Parameters:
+

xs (np.ndarray) – Input array.

+
+
Returns:
+

The calculated value of the quadratic function.

+
+
Return type:
+

float

+
+
+

Notes

+

It has one global minimum f(xs)=0 at xs = [0,0,…,0].

+
+ +
+
+odatse.solver.analytical.quartics(xs: ndarray) → float[source]
+

Quartic function with two global minima.

+
+
Parameters:
+

xs (np.ndarray) – Input array.

+
+
Returns:
+

The calculated value of the quartic function.

+
+
Return type:
+

float

+
+
+

Notes

+

It has two global minima f(xs)=0 at xs = [1,1,…,1] and [0,0,…,0]. +It has one saddle point f(0,0,…,0) = 1.0.

+
+ +
+
+odatse.solver.analytical.rosenbrock(xs: ndarray) → float[source]
+

Rosenbrock’s function.

+
+
Parameters:
+

xs (np.ndarray) – Input array.

+
+
Returns:
+

The calculated value of Rosenbrock’s function.

+
+
Return type:
+

float

+
+
+

Notes

+

It has one global minimum f(xs) = 0 at xs=[1,1,…,1].

+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.solver.function.html b/manual/v3.0.0/api/odatse.solver.function.html new file mode 100644 index 00000000..731e3d24 --- /dev/null +++ b/manual/v3.0.0/api/odatse.solver.function.html @@ -0,0 +1,227 @@ + + + + + + + + + odatse.solver.function module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.solver.function module

+
+
+class odatse.solver.function.Solver(info: Info)[source]
+

Bases: SolverBase

+

Solver class for evaluating functions with given parameters.

+

Initialize the solver.

+
+
Parameters:
+

info (Info) – Information object containing solver configuration.

+
+
+
+
+__init__(info: Info) → None[source]
+

Initialize the solver.

+
+
Parameters:
+

info (Info) – Information object containing solver configuration.

+
+
+
+ +
+
+evaluate(x: ndarray, args: Tuple = (), nprocs: int = 1, nthreads: int = 1) → float[source]
+

Evaluate the function with given parameters.

+
+
Parameters:
+
    +

  • x (np.ndarray) – Input array for the function.

    • +

  • args (Tuple, optional) – Additional arguments for the function.

    • +

  • nprocs (int, optional) – Number of processes to use.

    • +

  • nthreads (int, optional) – Number of threads to use.

    • +
+
+
Returns:
+

Result of the function evaluation.

+
+
Return type:
+

float

+
+
+
+ +
+
+get_results() → float[source]
+

Get the results of the function evaluation.

+
+
Returns:
+

Result of the function evaluation.

+
+
Return type:
+

float

+
+
+
+ +
+
+prepare(x: ndarray, args=()) → None[source]
+

Prepare the solver with the given parameters.

+
+
Parameters:
+
    +

  • x (np.ndarray) – Input array for the function.

    • +

  • args (tuple, optional) – Additional arguments for the function.

    • +
+
+
+
+ +
+
+run(nprocs: int = 1, nthreads: int = 1) → None[source]
+

Run the function evaluation.

+
+
Parameters:
+
    +

  • nprocs (int, optional) – Number of processes to use.

    • +

  • nthreads (int, optional) – Number of threads to use.

    • +
+
+
Raises:
+

RuntimeError – If the function is not set.

+
+
+
+ +
+
+set_function(f: Callable[[ndarray], float]) → None[source]
+

Set the function to be evaluated.

+
+
Parameters:
+

f (Callable[[np.ndarray], float]) – Function to be evaluated.

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.solver.html b/manual/v3.0.0/api/odatse.solver.html new file mode 100644 index 00000000..f882afa7 --- /dev/null +++ b/manual/v3.0.0/api/odatse.solver.html @@ -0,0 +1,134 @@ + + + + + + + + + odatse.solver package — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.solver package

+
+

Submodules

+
+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.graph.html b/manual/v3.0.0/api/odatse.util.graph.html new file mode 100644 index 00000000..0bcc67af --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.graph.html @@ -0,0 +1,159 @@ + + + + + + + + + odatse.util.graph module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.graph module

+
+
+odatse.util.graph.is_bidirectional(nnlist: List[List[int]]) → bool[source]
+

Check if the graph represented by the neighbor list is bidirectional.

+
+
Parameters:
+

nnlist (List[List[int]]) – A list of lists where each sublist represents the neighbors of a node.

+
+
Returns:
+

True if the graph is bidirectional, False otherwise.

+
+
Return type:
+

bool

+
+
+
+ +
+
+odatse.util.graph.is_connected(nnlist: List[List[int]]) → bool[source]
+

Check if the graph represented by the neighbor list is connected.

+
+
Parameters:
+

nnlist (List[List[int]]) – A list of lists where each sublist represents the neighbors of a node.

+
+
Returns:
+

True if the graph is connected, False otherwise.

+
+
Return type:
+

bool

+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.html b/manual/v3.0.0/api/odatse.util.html new file mode 100644 index 00000000..772a0e99 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.html @@ -0,0 +1,140 @@ + + + + + + + + + odatse.util package — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.limitation.html b/manual/v3.0.0/api/odatse.util.limitation.html new file mode 100644 index 00000000..b7ca5fbe --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.limitation.html @@ -0,0 +1,263 @@ + + + + + + + + + odatse.util.limitation module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.limitation module

+
+
+class odatse.util.limitation.Inequality(a: ndarray, b: ndarray, is_limitary: bool)[source]
+

Bases: LimitationBase

+

Class representing an inequality limitation.

+

Initialize the inequality limitation.

+
+
Parameters:
+
    +

  • a (np.ndarray) – Coefficient matrix.

    • +

  • b (np.ndarray) – Constant vector.

    • +

  • is_limitary (bool) – Boolean indicating if the limitation is active.

    • +
+
+
+
+
+__init__(a: ndarray, b: ndarray, is_limitary: bool)[source]
+

Initialize the inequality limitation.

+
+
Parameters:
+
    +

  • a (np.ndarray) – Coefficient matrix.

    • +

  • b (np.ndarray) – Constant vector.

    • +

  • is_limitary (bool) – Boolean indicating if the limitation is active.

    • +
+
+
+
+ +
+
+classmethod from_dict(d)[source]
+

Create an Inequality instance from a dictionary.

+
+
Parameters:
+

d – Dictionary containing ‘co_a’ and ‘co_b’ keys.

+
+
Returns:
+

an Inequality instance.

+
+
Return type:
+

Inequality

+
+
+
+ +
+
+judge(x: ndarray) → bool[source]
+

Judge if the inequality limitation is satisfied.

+
+
Parameters:
+

x (np.ndarray) – Input array to be judged.

+
+
Returns:
+

Boolean indicating if the limitation is satisfied.

+
+
Return type:
+

bool

+
+
+
+ +
+ +
+
+class odatse.util.limitation.LimitationBase(is_limitary: bool)[source]
+

Bases: object

+

Abstract base class for limitations.

+

Initialize the limitation.

+
+
Parameters:
+

is_limitary (bool) – Boolean indicating if the limitation is active.

+
+
+
+
+abstract __init__(is_limitary: bool)[source]
+

Initialize the limitation.

+
+
Parameters:
+

is_limitary (bool) – Boolean indicating if the limitation is active.

+
+
+
+ +
+
+abstract judge(x: ndarray) → bool[source]
+

Abstract method to judge if the limitation is satisfied.

+
+
Parameters:
+

x (np.ndarray) – Input array to be judged.

+
+
Returns:
+

Boolean indicating if the limitation is satisfied.

+
+
Return type:
+

bool

+
+
+
+ +
+ +
+
+class odatse.util.limitation.Unlimited[source]
+

Bases: LimitationBase

+

Class representing an unlimited (no limitation) condition.

+

Initialize the unlimited condition.

+
+
+__init__()[source]
+

Initialize the unlimited condition.

+
+ +
+
+judge(x: ndarray) → bool[source]
+

Always returns True as there is no limitation.

+
+
Parameters:
+

x (np.ndarray) – Input array to be judged.

+
+
Returns:
+

Always True.

+
+
Return type:
+

bool

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.logger.html b/manual/v3.0.0/api/odatse.util.logger.html new file mode 100644 index 00000000..26986370 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.logger.html @@ -0,0 +1,211 @@ + + + + + + + + + odatse.util.logger module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.logger module

+
+
+class odatse.util.logger.Logger(info: Info | None = None, *, buffer_size: int = 0, filename: str = 'runner.log', write_input: bool = False, write_result: bool = False, params: Dict[str, Any] | None = None, **rest)[source]
+

Bases: object

+

Logger class to handle logging of calls, elapsed time, and optionally input and result data.

+

Initialize the Logger.

+
+
Parameters:
+
    +

  • info (Info, optional) – Information object containing logging parameters.

    • +

  • buffer_size (int) – Size of the buffer before writing to the log file.

    • +

  • filename (str) – Name of the log file.

    • +

  • write_input (bool) – Flag to indicate if input should be logged.

    • +

  • write_result (bool) – Flag to indicate if result should be logged.

    • +

  • params (Dict[str,Any]], optional) – Additional parameters for logging.

    • +

  • **rest – Additional keyword arguments.

    • +
+
+
+
+
+__init__(info: Info | None = None, *, buffer_size: int = 0, filename: str = 'runner.log', write_input: bool = False, write_result: bool = False, params: Dict[str, Any] | None = None, **rest) → None[source]
+

Initialize the Logger.

+
+
Parameters:
+
    +

  • info (Info, optional) – Information object containing logging parameters.

    • +

  • buffer_size (int) – Size of the buffer before writing to the log file.

    • +

  • filename (str) – Name of the log file.

    • +

  • write_input (bool) – Flag to indicate if input should be logged.

    • +

  • write_result (bool) – Flag to indicate if result should be logged.

    • +

  • params (Dict[str,Any]], optional) – Additional parameters for logging.

    • +

  • **rest – Additional keyword arguments.

    • +
+
+
+
+ +
+
+count(x: ndarray, args, result: float) → None[source]
+

Log a call with input and result data.

+
+
Parameters:
+
    +

  • x (np.ndarray) – Input data.

    • +

  • args – Additional arguments.

    • +

  • result (float) – Result data.

    • +
+
+
+
+ +
+
+is_active() → bool[source]
+

Check if logging is active.

+
+
Returns:
+

True if logging is active, False otherwise.

+
+
Return type:
+

bool

+
+
+
+ +
+
+prepare(proc_dir: Path) → None[source]
+

Prepare the log file for writing.

+
+
Parameters:
+

proc_dir (Path) – Directory where the log file will be created.

+
+
+
+ +
+
+write() → None[source]
+

Write the buffered log entries to the log file.

+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.mapping.html b/manual/v3.0.0/api/odatse.util.mapping.html new file mode 100644 index 00000000..6874e958 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.mapping.html @@ -0,0 +1,186 @@ + + + + + + + + + odatse.util.mapping module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.mapping module

+
+
+class odatse.util.mapping.Affine(A: ndarray | None = None, b: ndarray | None = None)[source]
+

Bases: MappingBase

+

An affine mapping defined by a matrix A and a vector b.

+

Initialize the affine mapping.

+
+
Parameters:
+
    +

  • A (np.ndarray, optional) – Transformation matrix.

    • +

  • b (np.ndarray, optional) – Translation vector.

    • +
+
+
+
+
+__init__(A: ndarray | None = None, b: ndarray | None = None)[source]
+

Initialize the affine mapping.

+
+
Parameters:
+
    +

  • A (np.ndarray, optional) – Transformation matrix.

    • +

  • b (np.ndarray, optional) – Translation vector.

    • +
+
+
+
+ +
+
+classmethod from_dict(d)[source]
+

Create an Affine instance from a dictionary.

+
+
Parameters:
+

d (dict) – Dictionary containing ‘A’ and ‘b’ keys.

+
+
Returns:
+

An instance of the Affine class.

+
+
Return type:
+

Affine

+
+
+
+ +
+ +
+
+class odatse.util.mapping.MappingBase[source]
+

Bases: object

+

Base class for mapping operations.

+
+ +
+
+class odatse.util.mapping.TrivialMapping[source]
+

Bases: MappingBase

+

A trivial mapping that returns the input array unchanged.

+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.neighborlist.html b/manual/v3.0.0/api/odatse.util.neighborlist.html new file mode 100644 index 00000000..3d4129f8 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.neighborlist.html @@ -0,0 +1,365 @@ + + + + + + + + + odatse.util.neighborlist module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.neighborlist module

+
+
+class odatse.util.neighborlist.Cells(mins: ndarray, maxs: ndarray, cellsize: float)[source]
+

Bases: object

+

A class to represent a grid of cells for spatial partitioning.

+

Initialize the Cells object.

+
+
Parameters:
+
    +

  • mins (np.ndarray) – The minimum coordinates of the grid.

    • +

  • maxs (np.ndarray) – The maximum coordinates of the grid.

    • +

  • cellsize (float) – The size of each cell.

    • +
+
+
+
+
+__init__(mins: ndarray, maxs: ndarray, cellsize: float)[source]
+

Initialize the Cells object.

+
+
Parameters:
+
    +

  • mins (np.ndarray) – The minimum coordinates of the grid.

    • +

  • maxs (np.ndarray) – The maximum coordinates of the grid.

    • +

  • cellsize (float) – The size of each cell.

    • +
+
+
+
+ +
+
+cellcoord2cellindex(ns: ndarray) → int[source]
+

Convert cell coordinates to a cell index.

+
+
Parameters:
+

ns (np.ndarray) – The cell coordinates to convert.

+
+
Returns:
+

The index of the cell.

+
+
Return type:
+

int

+
+
+
+ +
+
+cellindex2cellcoord(index: int) → ndarray[source]
+

Convert a cell index to cell coordinates.

+
+
Parameters:
+

index (int) – The index of the cell.

+
+
Returns:
+

The cell coordinates.

+
+
Return type:
+

np.ndarray

+
+
+
+ +
+
+coord2cellcoord(x: ndarray) → ndarray[source]
+

Convert coordinates to cell coordinates.

+
+
Parameters:
+

x (np.ndarray) – The coordinates to convert.

+
+
Returns:
+

The cell coordinates.

+
+
Return type:
+

np.ndarray

+
+
+
+ +
+
+coord2cellindex(x: ndarray) → int[source]
+

Convert coordinates to a cell index.

+
+
Parameters:
+

x (np.ndarray) – The coordinates to convert.

+
+
Returns:
+

The index of the cell.

+
+
Return type:
+

int

+
+
+
+ +
+
+neighborcells(index: int) → List[int][source]
+

Get the indices of neighboring cells.

+
+
Parameters:
+

index (int) – The index of the cell.

+
+
Returns:
+

The indices of the neighboring cells.

+
+
Return type:
+

List[int]

+
+
+
+ +
+
+out_of_bound(ns: ndarray) → bool[source]
+

Check if cell coordinates are out of bounds.

+
+
Parameters:
+

ns (np.ndarray) – The cell coordinates to check.

+
+
Returns:
+

True if out of bounds, False otherwise.

+
+
Return type:
+

bool

+
+
+
+ +
+ +
+
+odatse.util.neighborlist.load_neighbor_list(filename: PathLike, nnodes: int = None) → List[List[int]][source]
+

Load a neighbor list from a file.

+
+
Parameters:
+
    +

  • filename (PathLike) – The path to the file containing the neighbor list.

    • +

  • nnodes (int, optional) – The number of nodes. If None, it will be determined from the file.

    • +
+
+
Returns:
+

The neighbor list.

+
+
Return type:
+

List[List[int]]

+
+
+
+ +
+
+odatse.util.neighborlist.make_neighbor_list(X: ndarray, radius: float, allow_selfloop: bool = False, check_allpairs: bool = False, show_progress: bool = False, comm: Comm = None) → List[List[int]][source]
+

Create a neighbor list for given points.

+
+
Parameters:
+
    +

  • X (np.ndarray) – The coordinates of the points.

    • +

  • radius (float) – The radius within which neighbors are considered.

    • +

  • allow_selfloop (bool) – Whether to allow self-loops in the neighbor list.

    • +

  • check_allpairs (bool) – Whether to use the naive all-pairs approach.

    • +

  • show_progress (bool) – Whether to show a progress bar.

    • +

  • comm (mpi.Comm, optional) – The MPI communicator.

    • +
+
+
Returns:
+

The neighbor list.

+
+
Return type:
+

List[List[int]]

+
+
+
+ +
+
+odatse.util.neighborlist.make_neighbor_list_cell(X: ndarray, radius: float, allow_selfloop: bool, show_progress: bool, comm: Comm = None) → List[List[int]][source]
+

Create a neighbor list using cell-based spatial partitioning.

+
+
Parameters:
+
    +

  • X (np.ndarray) – The coordinates of the points.

    • +

  • radius (float) – The radius within which neighbors are considered.

    • +

  • allow_selfloop (bool) – Whether to allow self-loops in the neighbor list.

    • +

  • show_progress (bool) – Whether to show a progress bar.

    • +

  • comm (mpi.Comm, optional) – The MPI communicator.

    • +
+
+
Returns:
+

The neighbor list.

+
+
Return type:
+

List[List[int]]

+
+
+
+ +
+
+odatse.util.neighborlist.make_neighbor_list_naive(X: ndarray, radius: float, allow_selfloop: bool, show_progress: bool, comm: Comm = None) → List[List[int]][source]
+

Create a neighbor list using a naive all-pairs approach.

+
+
Parameters:
+
    +

  • X (np.ndarray)) – The coordinates of the points.

    • +

  • radius (float) – The radius within which neighbors are considered.

    • +

  • allow_selfloop (bool) – Whether to allow self-loops in the neighbor list.

    • +

  • show_progress (bool) – Whether to show a progress bar.

    • +

  • comm (mpi.Comm, optional) – The MPI communicator.

    • +
+
+
Returns:
+

The neighbor list.

+
+
Return type:
+

List[List[int]]

+
+
+
+ +
+
+odatse.util.neighborlist.write_neighbor_list(filename: str, nnlist: List[List[int]], radius: float = None, unit: ndarray = None)[source]
+

Write the neighbor list to a file.

+
+
Parameters:
+
    +

  • filename (str) – The path to the output file.

    • +

  • nnlist (List[List[int]]) – The neighbor list to write.

    • +

  • radius (float, optional) – The neighborhood radius. Defaults to None.

    • +

  • unit (np.ndarray, optional) – The unit for each coordinate. Defaults to None.

    • +
+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.read_matrix.html b/manual/v3.0.0/api/odatse.util.read_matrix.html new file mode 100644 index 00000000..d6b31a89 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.read_matrix.html @@ -0,0 +1,165 @@ + + + + + + + + + odatse.util.read_matrix module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.read_matrix module

+
+
+odatse.util.read_matrix.read_matrix(inp: str | List[List[float]]) → ndarray[source]
+

Converts an input string or list of lists of floats into a numpy array matrix.

+
+
Parameters:
+

inp (Union[str, List[List[float]]]) – Input data, either as a string with rows of space-separated numbers or a list of lists of floats.

+
+
Returns:
+

A numpy array representing the matrix.

+
+
Return type:
+

np.ndarray

+
+
Raises:
+

RuntimeError – If the input is not a matrix.

+
+
+
+ +
+
+odatse.util.read_matrix.read_vector(inp: str | List[float]) → ndarray[source]
+

Converts an input string or list of floats into a numpy array vector.

+
+
Parameters:
+

inp (Union[str, List[float]]) – Input data, either as a space-separated string of numbers or a list of floats.

+
+
Returns:
+

A numpy array representing the vector.

+
+
Return type:
+

np.ndarray

+
+
Raises:
+

RuntimeError – If the input is not a vector.

+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.resampling.html b/manual/v3.0.0/api/odatse.util.resampling.html new file mode 100644 index 00000000..cc37e202 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.resampling.html @@ -0,0 +1,279 @@ + + + + + + + + + odatse.util.resampling module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.resampling module

+
+
+class odatse.util.resampling.BinarySearch(weights: Iterable)[source]
+

Bases: Resampler

+

A resampler that uses binary search to sample based on given weights.

+

Initialize the BinarySearch resampler with the given weights.

+
+
Parameters:
+

weights (Iterable) – An iterable of weights.

+
+
+
+
+__init__(weights: Iterable)[source]
+

Initialize the BinarySearch resampler with the given weights.

+
+
Parameters:
+

weights (Iterable) – An iterable of weights.

+
+
+
+ +
+
+_sample(r: float) → int[source]
+

Perform a binary search to find the index corresponding to the given random number.

+
+
Parameters:
+

r (float) – A random number scaled by the maximum weight.

+
+
Returns:
+

The index corresponding to the random number.

+
+
Return type:
+

int

+
+
+
+ +
+
+reset(weights: Iterable)[source]
+

Reset the resampler with new weights.

+
+
Parameters:
+

weights (Iterable) – An iterable of weights.

+
+
+
+ +
+
+sample(rs: RandomState) → int[source]
+
+sample(rs: RandomState, size) → ndarray
+

Sample indices based on the weights.

+
+
Parameters:
+
    +

  • rs (np.random.RandomState) – A random state for generating random numbers.

    • +

  • size – The number of samples to generate. If None, a single sample is generated.

    • +
+
+
Returns:
+

A single sampled index or an array of sampled indices.

+
+
Return type:
+

int or np.ndarray

+
+
+
+ +
+ +
+
+class odatse.util.resampling.Resampler[source]
+

Bases: ABC

+
+ +
+
+class odatse.util.resampling.WalkerTable(weights: Iterable)[source]
+

Bases: Resampler

+

A resampler that uses Walker’s alias method to sample based on given weights.

+

Initialize the WalkerTable resampler with the given weights.

+
+
Parameters:
+

weights (Iterable) – An iterable of weights.

+
+
+
+
+__init__(weights: Iterable)[source]
+

Initialize the WalkerTable resampler with the given weights.

+
+
Parameters:
+

weights (Iterable) – An iterable of weights.

+
+
+
+ +
+
+_sample(r: float) → int[source]
+

Perform a sampling operation based on the given random number.

+
+
Parameters:
+

r (float) – A random number scaled by the number of weights.

+
+
Returns:
+

The index corresponding to the random number.

+
+
Return type:
+

int

+
+
+
+ +
+
+reset(weights: Iterable)[source]
+

Reset the resampler with new weights.

+
+
Parameters:
+

weights (Iterable) – An iterable of weights.

+
+
+
+ +
+
+sample(rs: RandomState) → int[source]
+
+sample(rs: RandomState, size) → ndarray
+

Sample indices based on the weights.

+
+
Parameters:
+
    +

  • rs (np.random.RandomState) – A random state for generating random numbers.

    • +

  • size – The number of samples to generate. If None, a single sample is generated.

    • +
+
+
Returns:
+

A single sampled index or an array of sampled indices.

+
+
Return type:
+

int or np.ndarray

+
+
+
+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.separateT.html b/manual/v3.0.0/api/odatse.util.separateT.html new file mode 100644 index 00000000..ebd7939a --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.separateT.html @@ -0,0 +1,192 @@ + + + + + + + + + odatse.util.separateT module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.separateT module

+
+
+class odatse.util.separateT.Entry(step, walker, fx, xs)
+

Bases: tuple

+

Create new instance of Entry(step, walker, fx, xs)

+
+
+_asdict()
+

Return a new dict which maps field names to their values.

+
+ +
+
+classmethod _make(iterable)
+

Make a new Entry object from a sequence or iterable

+
+ +
+
+_replace(**kwds)
+

Return a new Entry object replacing specified fields with new values

+
+ +
+
+fx
+

Alias for field number 2

+
+ +
+
+step
+

Alias for field number 0

+
+ +
+
+walker
+

Alias for field number 1

+
+ +
+
+xs
+

Alias for field number 3

+
+ +
+ +
+
+odatse.util.separateT.separateT(Ts: ndarray, nwalkers: int, output_dir: PathLike, comm: Comm | None, use_beta: bool, buffer_size: int = 10000) → None[source]
+

Separates and processes temperature data for quantum beam diffraction experiments.

+
+
Parameters:
+
    +

  • Ts (np.ndarray) – Array of temperature values.

    • +

  • nwalkers (int) – Number of walkers.

    • +

  • output_dir (PathLike) – Directory to store the output files.

    • +

  • comm (mpi.Comm, optional) – MPI communicator for parallel processing.

    • +

  • use_beta (bool) – Flag to determine if beta values are used instead of temperature.

    • +

  • buffer_size (int, optional) – Size of the buffer for reading input data. Default is 10000.

    • +
+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/odatse.util.toml.html b/manual/v3.0.0/api/odatse.util.toml.html new file mode 100644 index 00000000..b715a9d9 --- /dev/null +++ b/manual/v3.0.0/api/odatse.util.toml.html @@ -0,0 +1,142 @@ + + + + + + + + + odatse.util.toml module — ODAT-SE API documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

odatse.util.toml module

+
+
+odatse.util.toml.load(path: str) → MutableMapping[str, Any][source]
+

read TOML file

+
+
Parameters:
+

path (str) – File path to an input TOML file

+
+
Returns:
+

toml_dict – Dictionary representing TOML file

+
+
Return type:
+

MutableMapping[str, Any]

+
+
+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/py-modindex.html b/manual/v3.0.0/api/py-modindex.html new file mode 100644 index 00000000..6b67ddc7 --- /dev/null +++ b/manual/v3.0.0/api/py-modindex.html @@ -0,0 +1,280 @@ + + + + + + + + Python Module Index — ODAT-SE API documentation + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Python Module Index
    • +
  • +
    • +
+
+
+
+
+ + +

Python Module Index

+ +
+ o +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 
+ o
+ odatse +
    + odatse._info +
    + odatse._initialize +
    + odatse._main +
    + odatse._runner +
    + odatse.algorithm +
    + odatse.algorithm._algorithm +
    + odatse.algorithm.bayes +
    + odatse.algorithm.exchange +
    + odatse.algorithm.mapper_mpi +
    + odatse.algorithm.min_search +
    + odatse.algorithm.montecarlo +
    + odatse.algorithm.pamc +
    + odatse.domain +
    + odatse.domain._domain +
    + odatse.domain.meshgrid +
    + odatse.domain.region +
    + odatse.exception +
    + odatse.mpi +
    + odatse.solver +
    + odatse.solver._solver +
    + odatse.solver.analytical +
    + odatse.solver.function +
    + odatse.util +
    + odatse.util.graph +
    + odatse.util.limitation +
    + odatse.util.logger +
    + odatse.util.mapping +
    + odatse.util.neighborlist +
    + odatse.util.read_matrix +
    + odatse.util.resampling +
    + odatse.util.separateT +
    + odatse.util.toml +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/search.html b/manual/v3.0.0/api/search.html new file mode 100644 index 00000000..44a83a40 --- /dev/null +++ b/manual/v3.0.0/api/search.html @@ -0,0 +1,120 @@ + + + + + + + + Search — ODAT-SE API documentation + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+ +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/manual/v3.0.0/api/searchindex.js b/manual/v3.0.0/api/searchindex.js new file mode 100644 index 00000000..794ed100 --- /dev/null +++ b/manual/v3.0.0/api/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"alltitles": {"Contents:": [[0, null]], "Indices and tables": [[0, "indices-and-tables"]], "Submodules": [[2, "submodules"], [7, "submodules"], [15, "submodules"], [21, "submodules"], [25, "submodules"]], "Subpackages": [[2, "subpackages"]], "Welcome to ODAT-SE API\u2019s documentation!": [[0, null]], "odatse": [[1, null]], "odatse package": [[2, null]], "odatse._info module": [[3, null]], "odatse._initialize module": [[4, null]], "odatse._main module": [[5, null]], "odatse._runner module": [[6, null]], "odatse.algorithm package": [[7, null]], "odatse.algorithm._algorithm module": [[8, null]], "odatse.algorithm.bayes module": [[9, null]], "odatse.algorithm.exchange module": [[10, null]], "odatse.algorithm.mapper_mpi module": [[11, null]], "odatse.algorithm.min_search module": [[12, null]], "odatse.algorithm.montecarlo module": [[13, null]], "odatse.algorithm.pamc module": [[14, null]], "odatse.domain package": [[15, null]], "odatse.domain._domain module": [[16, null]], "odatse.domain.meshgrid module": [[17, null]], "odatse.domain.region module": [[18, null]], "odatse.exception module": [[19, null]], "odatse.mpi module": [[20, null]], "odatse.solver package": [[21, null]], "odatse.solver._solver module": [[22, null]], "odatse.solver.analytical module": [[23, null]], "odatse.solver.function module": [[24, null]], "odatse.util package": [[25, null]], "odatse.util.graph module": [[26, null]], "odatse.util.limitation module": [[27, null]], "odatse.util.logger module": [[28, null]], "odatse.util.mapping module": [[29, null]], "odatse.util.neighborlist module": [[30, null]], "odatse.util.read_matrix module": [[31, null]], "odatse.util.resampling module": [[32, null]], "odatse.util.separateT module": [[33, null]], "odatse.util.toml module": [[34, null]]}, "docnames": ["index", "modules", "odatse", "odatse._info", "odatse._initialize", "odatse._main", "odatse._runner", "odatse.algorithm", "odatse.algorithm._algorithm", "odatse.algorithm.bayes", "odatse.algorithm.exchange", "odatse.algorithm.mapper_mpi", "odatse.algorithm.min_search", "odatse.algorithm.montecarlo", "odatse.algorithm.pamc", "odatse.domain", "odatse.domain._domain", "odatse.domain.meshgrid", "odatse.domain.region", "odatse.exception", "odatse.mpi", "odatse.solver", "odatse.solver._solver", "odatse.solver.analytical", "odatse.solver.function", "odatse.util", "odatse.util.graph", "odatse.util.limitation", "odatse.util.logger", "odatse.util.mapping", "odatse.util.neighborlist", "odatse.util.read_matrix", "odatse.util.resampling", "odatse.util.separateT", "odatse.util.toml"], "envversion": {"sphinx": 64, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.todo": 2, "sphinx.ext.viewcode": 1}, "filenames": ["index.rst", "modules.rst", "odatse.rst", "odatse._info.rst", "odatse._initialize.rst", "odatse._main.rst", "odatse._runner.rst", "odatse.algorithm.rst", "odatse.algorithm._algorithm.rst", "odatse.algorithm.bayes.rst", "odatse.algorithm.exchange.rst", "odatse.algorithm.mapper_mpi.rst", "odatse.algorithm.min_search.rst", "odatse.algorithm.montecarlo.rst", "odatse.algorithm.pamc.rst", "odatse.domain.rst", "odatse.domain._domain.rst", "odatse.domain.meshgrid.rst", "odatse.domain.region.rst", "odatse.exception.rst", "odatse.mpi.rst", "odatse.solver.rst", "odatse.solver._solver.rst", "odatse.solver.analytical.rst", "odatse.solver.function.rst", "odatse.util.rst", "odatse.util.graph.rst", "odatse.util.limitation.rst", "odatse.util.logger.rst", "odatse.util.mapping.rst", "odatse.util.neighborlist.rst", "odatse.util.read_matrix.rst", "odatse.util.resampling.rst", "odatse.util.separateT.rst", "odatse.util.toml.rst"], "indexentries": {"__exchange_multi_walker() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm.__exchange_multi_walker", false]], "__exchange_single_walker() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm.__exchange_single_walker", false]], "__init__() (odatse._info.info method)": [[3, "odatse._info.Info.__init__", false]], "__init__() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.__init__", false]], "__init__() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm.__init__", false]], "__init__() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm.__init__", false]], "__init__() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm.__init__", false]], "__init__() (odatse.algorithm.min_search.algorithm method)": [[12, "odatse.algorithm.min_search.Algorithm.__init__", false]], "__init__() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.__init__", false]], "__init__() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm.__init__", false]], "__init__() (odatse.domain._domain.domainbase method)": [[16, "odatse.domain._domain.DomainBase.__init__", false]], "__init__() (odatse.domain.meshgrid.meshgrid method)": [[17, "odatse.domain.meshgrid.MeshGrid.__init__", false]], "__init__() (odatse.domain.region.region method)": [[18, "odatse.domain.region.Region.__init__", false]], "__init__() (odatse.solver._solver.solverbase method)": [[22, "odatse.solver._solver.SolverBase.__init__", false]], "__init__() (odatse.solver.analytical.solver method)": [[23, "odatse.solver.analytical.Solver.__init__", false]], "__init__() (odatse.solver.function.solver method)": [[24, "odatse.solver.function.Solver.__init__", false]], "__init__() (odatse.util.limitation.inequality method)": [[27, "odatse.util.limitation.Inequality.__init__", false]], "__init__() (odatse.util.limitation.limitationbase method)": [[27, "odatse.util.limitation.LimitationBase.__init__", false]], "__init__() (odatse.util.limitation.unlimited method)": [[27, "odatse.util.limitation.Unlimited.__init__", false]], "__init__() (odatse.util.logger.logger method)": [[28, "odatse.util.logger.Logger.__init__", false]], "__init__() (odatse.util.mapping.affine method)": [[29, "odatse.util.mapping.Affine.__init__", false]], "__init__() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.__init__", false]], "__init__() (odatse.util.resampling.binarysearch method)": [[32, "odatse.util.resampling.BinarySearch.__init__", false]], "__init__() (odatse.util.resampling.walkertable method)": [[32, "odatse.util.resampling.WalkerTable.__init__", false]], "__init_rng() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.__init_rng", false]], "_asdict() (odatse.util.separatet.entry method)": [[33, "odatse.util.separateT.Entry._asdict", false]], "_check_parameters() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._check_parameters", false]], "_cleanup() (odatse._info.info method)": [[3, "odatse._info.Info._cleanup", false]], "_evaluate() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase._evaluate", false]], "_exchange() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._exchange", false]], "_find_scheduling() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._find_scheduling", false]], "_gather_information() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._gather_information", false]], "_init_random() (odatse.domain.region.region method)": [[18, "odatse.domain.region.Region._init_random", false]], "_initialize() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm._initialize", false]], "_initialize() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._initialize", false]], "_initialize() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._initialize", false]], "_initialize() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase._initialize", false]], "_initialize() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._initialize", false]], "_load_data() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._load_data", false]], "_load_state() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm._load_state", false]], "_load_state() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._load_state", false]], "_load_state() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._load_state", false]], "_load_state() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._load_state", false]], "_make() (odatse.util.separatet.entry class method)": [[33, "odatse.util.separateT.Entry._make", false]], "_output_results() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._output_results", false]], "_output_results() (odatse.algorithm.min_search.algorithm method)": [[12, "odatse.algorithm.min_search.Algorithm._output_results", false]], "_post() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._post", false]], "_post() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm._post", false]], "_post() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._post", false]], "_post() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._post", false]], "_post() (odatse.algorithm.min_search.algorithm method)": [[12, "odatse.algorithm.min_search.Algorithm._post", false]], "_post() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._post", false]], "_prepare() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._prepare", false]], "_prepare() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm._prepare", false]], "_prepare() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._prepare", false]], "_prepare() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._prepare", false]], "_prepare() (odatse.algorithm.min_search.algorithm method)": [[12, "odatse.algorithm.min_search.Algorithm._prepare", false]], "_prepare() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._prepare", false]], "_print_info() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._print_info", false]], "_replace() (odatse.util.separatet.entry method)": [[33, "odatse.util.separateT.Entry._replace", false]], "_resample() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._resample", false]], "_resample_fixed() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._resample_fixed", false]], "_resample_varied() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._resample_varied", false]], "_run() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._run", false]], "_run() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm._run", false]], "_run() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._run", false]], "_run() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._run", false]], "_run() (odatse.algorithm.min_search.algorithm method)": [[12, "odatse.algorithm.min_search.Algorithm._run", false]], "_run() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._run", false]], "_sample() (odatse.util.resampling.binarysearch method)": [[32, "odatse.util.resampling.BinarySearch._sample", false]], "_sample() (odatse.util.resampling.walkertable method)": [[32, "odatse.util.resampling.WalkerTable._sample", false]], "_save_data() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._save_data", false]], "_save_state() (odatse.algorithm.bayes.algorithm method)": [[9, "odatse.algorithm.bayes.Algorithm._save_state", false]], "_save_state() (odatse.algorithm.exchange.algorithm method)": [[10, "odatse.algorithm.exchange.Algorithm._save_state", false]], "_save_state() (odatse.algorithm.mapper_mpi.algorithm method)": [[11, "odatse.algorithm.mapper_mpi.Algorithm._save_state", false]], "_save_state() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._save_state", false]], "_save_stats() (odatse.algorithm.pamc.algorithm method)": [[14, "odatse.algorithm.pamc.Algorithm._save_stats", false]], "_setup() (odatse.domain.meshgrid.meshgrid method)": [[17, "odatse.domain.meshgrid.MeshGrid._setup", false]], "_setup() (odatse.domain.region.region method)": [[18, "odatse.domain.region.Region._setup", false]], "_setup_from_file() (odatse.domain.meshgrid.meshgrid method)": [[17, "odatse.domain.meshgrid.MeshGrid._setup_from_file", false]], "_setup_grid() (odatse.domain.meshgrid.meshgrid method)": [[17, "odatse.domain.meshgrid.MeshGrid._setup_grid", false]], "_setup_neighbour() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase._setup_neighbour", false]], "_show_parameters() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase._show_parameters", false]], "_write_result() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase._write_result", false]], "_write_result_header() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase._write_result_header", false]], "ackley() (in module odatse.solver.analytical)": [[23, "odatse.solver.analytical.ackley", false]], "affine (class in odatse.util.mapping)": [[29, "odatse.util.mapping.Affine", false]], "algorithm (class in odatse.algorithm.bayes)": [[9, "odatse.algorithm.bayes.Algorithm", false]], "algorithm (class in odatse.algorithm.exchange)": [[10, "odatse.algorithm.exchange.Algorithm", false]], "algorithm (class in odatse.algorithm.mapper_mpi)": [[11, "odatse.algorithm.mapper_mpi.Algorithm", false]], "algorithm (class in odatse.algorithm.min_search)": [[12, "odatse.algorithm.min_search.Algorithm", false]], "algorithm (class in odatse.algorithm.pamc)": [[14, "odatse.algorithm.pamc.Algorithm", false]], "algorithmbase (class in odatse.algorithm._algorithm)": [[8, "odatse.algorithm._algorithm.AlgorithmBase", false]], "algorithmbase (class in odatse.algorithm.montecarlo)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase", false]], "algorithmstatus (class in odatse.algorithm._algorithm)": [[8, "odatse.algorithm._algorithm.AlgorithmStatus", false]], "bayes_max_num_probes (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.bayes_max_num_probes", false]], "best_action (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.best_action", false]], "best_fx (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.best_fx", false]], "best_fx (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.best_fx", false]], "best_fx (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.best_fx", false]], "best_fx (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.best_fx", false]], "best_istep (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.best_istep", false]], "best_istep (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.best_istep", false]], "best_istep (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.best_istep", false]], "best_iwalker (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.best_iwalker", false]], "best_x (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.best_x", false]], "best_x (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.best_x", false]], "best_x (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.best_x", false]], "betas (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.betas", false]], "binarysearch (class in odatse.util.resampling)": [[32, "odatse.util.resampling.BinarySearch", false]], "cellcoord2cellindex() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.cellcoord2cellindex", false]], "cellindex2cellcoord() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.cellindex2cellcoord", false]], "cells (class in odatse.util.neighborlist)": [[30, "odatse.util.neighborlist.Cells", false]], "choose_algorithm() (in module odatse.algorithm)": [[7, "odatse.algorithm.choose_algorithm", false]], "comm (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.comm", false]], "comm (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.comm", false]], "coord2cellcoord() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.coord2cellcoord", false]], "coord2cellindex() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.coord2cellindex", false]], "count() (odatse.util.logger.logger method)": [[28, "odatse.util.logger.Logger.count", false]], "do_split() (odatse.domain.meshgrid.meshgrid method)": [[17, "odatse.domain.meshgrid.MeshGrid.do_split", false]], "domainbase (class in odatse.domain._domain)": [[16, "odatse.domain._domain.DomainBase", false]], "entry (class in odatse.util.separatet)": [[33, "odatse.util.separateT.Entry", false]], "error": [[19, "odatse.exception.Error", false]], "evaluate() (odatse.solver._solver.solverbase method)": [[22, "odatse.solver._solver.SolverBase.evaluate", false]], "evaluate() (odatse.solver.function.solver method)": [[24, "odatse.solver.function.Solver.evaluate", false]], "exchange_direction (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.exchange_direction", false]], "flatten_dict() (in module odatse.algorithm._algorithm)": [[8, "odatse.algorithm._algorithm.flatten_dict", false]], "from_dict() (odatse._info.info method)": [[3, "odatse._info.Info.from_dict", false]], "from_dict() (odatse.domain.meshgrid.meshgrid class method)": [[17, "odatse.domain.meshgrid.MeshGrid.from_dict", false]], "from_dict() (odatse.util.limitation.inequality class method)": [[27, "odatse.util.limitation.Inequality.from_dict", false]], "from_dict() (odatse.util.mapping.affine class method)": [[29, "odatse.util.mapping.Affine.from_dict", false]], "from_file() (odatse._info.info class method)": [[3, "odatse._info.Info.from_file", false]], "from_file() (odatse.domain.meshgrid.meshgrid class method)": [[17, "odatse.domain.meshgrid.MeshGrid.from_file", false]], "fx (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.fx", false]], "fx (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.fx", false]], "fx (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.fx", false]], "fx (odatse.util.separatet.entry attribute)": [[33, "odatse.util.separateT.Entry.fx", false]], "fx_list (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.fx_list", false]], "get_results() (odatse.solver.function.solver method)": [[24, "odatse.solver.function.Solver.get_results", false]], "himmelblau() (in module odatse.solver.analytical)": [[23, "odatse.solver.analytical.himmelblau", false]], "inequality (class in odatse.util.limitation)": [[27, "odatse.util.limitation.Inequality", false]], "info (class in odatse._info)": [[3, "odatse._info.Info", false]], "initial_list (odatse.domain.region.region attribute)": [[18, "odatse.domain.region.Region.initial_list", false]], "initialize() (in module odatse._initialize)": [[4, "odatse._initialize.initialize", false]], "initialize() (odatse.domain.region.region method)": [[18, "odatse.domain.region.Region.initialize", false]], "inode (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.inode", false]], "inputerror": [[19, "odatse.exception.InputError", false]], "interval (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.interval", false]], "is_active() (odatse.util.logger.logger method)": [[28, "odatse.util.logger.Logger.is_active", false]], "is_bidirectional() (in module odatse.util.graph)": [[26, "odatse.util.graph.is_bidirectional", false]], "is_connected() (in module odatse.util.graph)": [[26, "odatse.util.graph.is_connected", false]], "istep (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.istep", false]], "istep (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.istep", false]], "istep (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.istep", false]], "judge() (odatse.util.limitation.inequality method)": [[27, "odatse.util.limitation.Inequality.judge", false]], "judge() (odatse.util.limitation.limitationbase method)": [[27, "odatse.util.limitation.LimitationBase.judge", false]], "judge() (odatse.util.limitation.unlimited method)": [[27, "odatse.util.limitation.Unlimited.judge", false]], "label_list (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.label_list", false]], "limitationbase (class in odatse.util.limitation)": [[27, "odatse.util.limitation.LimitationBase", false]], "linear_regression_test() (in module odatse.solver.analytical)": [[23, "odatse.solver.analytical.linear_regression_test", false]], "load() (in module odatse.util.toml)": [[34, "odatse.util.toml.load", false]], "load_neighbor_list() (in module odatse.util.neighborlist)": [[30, "odatse.util.neighborlist.load_neighbor_list", false]], "local_update() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.local_update", false]], "logger (class in odatse.util.logger)": [[28, "odatse.util.logger.Logger", false]], "logweights (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.logweights", false]], "main() (in module odatse._main)": [[5, "odatse._main.main", false]], "main() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.main", false]], "make_neighbor_list() (in module odatse.util.neighborlist)": [[30, "odatse.util.neighborlist.make_neighbor_list", false]], "make_neighbor_list_cell() (in module odatse.util.neighborlist)": [[30, "odatse.util.neighborlist.make_neighbor_list_cell", false]], "make_neighbor_list_naive() (in module odatse.util.neighborlist)": [[30, "odatse.util.neighborlist.make_neighbor_list_naive", false]], "mappingbase (class in odatse.util.mapping)": [[29, "odatse.util.mapping.MappingBase", false]], "max_list (odatse.domain.region.region attribute)": [[18, "odatse.domain.region.Region.max_list", false]], "mesh_list (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.mesh_list", false]], "meshgrid (class in odatse.domain.meshgrid)": [[17, "odatse.domain.meshgrid.MeshGrid", false]], "min_list (odatse.domain.region.region attribute)": [[18, "odatse.domain.region.Region.min_list", false]], "module": [[2, "module-odatse", false], [3, "module-odatse._info", false], [4, "module-odatse._initialize", false], [5, "module-odatse._main", false], [6, "module-odatse._runner", false], [7, "module-odatse.algorithm", false], [8, "module-odatse.algorithm._algorithm", false], [9, "module-odatse.algorithm.bayes", false], [10, "module-odatse.algorithm.exchange", false], [11, "module-odatse.algorithm.mapper_mpi", false], [12, "module-odatse.algorithm.min_search", false], [13, "module-odatse.algorithm.montecarlo", false], [14, "module-odatse.algorithm.pamc", false], [15, "module-odatse.domain", false], [16, "module-odatse.domain._domain", false], [17, "module-odatse.domain.meshgrid", false], [18, "module-odatse.domain.region", false], [19, "module-odatse.exception", false], [20, "module-odatse.mpi", false], [21, "module-odatse.solver", false], [22, "module-odatse.solver._solver", false], [23, "module-odatse.solver.analytical", false], [24, "module-odatse.solver.function", false], [25, "module-odatse.util", false], [26, "module-odatse.util.graph", false], [27, "module-odatse.util.limitation", false], [28, "module-odatse.util.logger", false], [29, "module-odatse.util.mapping", false], [30, "module-odatse.util.neighborlist", false], [31, "module-odatse.util.read_matrix", false], [32, "module-odatse.util.resampling", false], [33, "module-odatse.util.separateT", false], [34, "module-odatse.util.toml", false]], "mpirank (odatse.domain._domain.domainbase attribute)": [[16, "odatse.domain._domain.DomainBase.mpirank", false]], "mpisize (odatse.domain._domain.domainbase attribute)": [[16, "odatse.domain._domain.DomainBase.mpisize", false]], "name (odatse.solver._solver.solverbase property)": [[22, "odatse.solver._solver.SolverBase.name", false]], "neighborcells() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.neighborcells", false]], "nreplica (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.nreplica", false]], "nreplica (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.nreplica", false]], "num_rand_basis (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.num_rand_basis", false]], "nwalkers (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.nwalkers", false]], "odatse": [[2, "module-odatse", false]], "odatse._info": [[3, "module-odatse._info", false]], "odatse._initialize": [[4, "module-odatse._initialize", false]], "odatse._main": [[5, "module-odatse._main", false]], "odatse._runner": [[6, "module-odatse._runner", false]], "odatse.algorithm": [[7, "module-odatse.algorithm", false]], "odatse.algorithm._algorithm": [[8, "module-odatse.algorithm._algorithm", false]], "odatse.algorithm.bayes": [[9, "module-odatse.algorithm.bayes", false]], "odatse.algorithm.exchange": [[10, "module-odatse.algorithm.exchange", false]], "odatse.algorithm.mapper_mpi": [[11, "module-odatse.algorithm.mapper_mpi", false]], "odatse.algorithm.min_search": [[12, "module-odatse.algorithm.min_search", false]], "odatse.algorithm.montecarlo": [[13, "module-odatse.algorithm.montecarlo", false]], "odatse.algorithm.pamc": [[14, "module-odatse.algorithm.pamc", false]], "odatse.domain": [[15, "module-odatse.domain", false]], "odatse.domain._domain": [[16, "module-odatse.domain._domain", false]], "odatse.domain.meshgrid": [[17, "module-odatse.domain.meshgrid", false]], "odatse.domain.region": [[18, "module-odatse.domain.region", false]], "odatse.exception": [[19, "module-odatse.exception", false]], "odatse.mpi": [[20, "module-odatse.mpi", false]], "odatse.solver": [[21, "module-odatse.solver", false]], "odatse.solver._solver": [[22, "module-odatse.solver._solver", false]], "odatse.solver.analytical": [[23, "module-odatse.solver.analytical", false]], "odatse.solver.function": [[24, "module-odatse.solver.function", false]], "odatse.util": [[25, "module-odatse.util", false]], "odatse.util.graph": [[26, "module-odatse.util.graph", false]], "odatse.util.limitation": [[27, "module-odatse.util.limitation", false]], "odatse.util.logger": [[28, "module-odatse.util.logger", false]], "odatse.util.mapping": [[29, "module-odatse.util.mapping", false]], "odatse.util.neighborlist": [[30, "module-odatse.util.neighborlist", false]], "odatse.util.read_matrix": [[31, "module-odatse.util.read_matrix", false]], "odatse.util.resampling": [[32, "module-odatse.util.resampling", false]], "odatse.util.separatet": [[33, "module-odatse.util.separateT", false]], "odatse.util.toml": [[34, "module-odatse.util.toml", false]], "out_of_bound() (odatse.util.neighborlist.cells method)": [[30, "odatse.util.neighborlist.Cells.out_of_bound", false]], "output_dir (odatse.domain._domain.domainbase attribute)": [[16, "odatse.domain._domain.DomainBase.output_dir", false]], "param_list (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.param_list", false]], "post() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.post", false]], "prepare() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.prepare", false]], "prepare() (odatse.solver.function.solver method)": [[24, "odatse.solver.function.Solver.prepare", false]], "prepare() (odatse.util.logger.logger method)": [[28, "odatse.util.logger.Logger.prepare", false]], "propose() (odatse.algorithm.montecarlo.algorithmbase method)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.propose", false]], "quadratics() (in module odatse.solver.analytical)": [[23, "odatse.solver.analytical.quadratics", false]], "quartics() (in module odatse.solver.analytical)": [[23, "odatse.solver.analytical.quartics", false]], "random_max_num_probes (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.random_max_num_probes", false]], "rank (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.rank", false]], "rank (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.rank", false]], "read_matrix() (in module odatse.util.read_matrix)": [[31, "odatse.util.read_matrix.read_matrix", false]], "read_ts() (in module odatse.algorithm.montecarlo)": [[13, "odatse.algorithm.montecarlo.read_Ts", false]], "read_vector() (in module odatse.util.read_matrix)": [[31, "odatse.util.read_matrix.read_vector", false]], "region (class in odatse.domain.region)": [[18, "odatse.domain.region.Region", false]], "rep2t (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.rep2T", false]], "resampler (class in odatse.util.resampling)": [[32, "odatse.util.resampling.Resampler", false]], "reset() (odatse.util.resampling.binarysearch method)": [[32, "odatse.util.resampling.BinarySearch.reset", false]], "reset() (odatse.util.resampling.walkertable method)": [[32, "odatse.util.resampling.WalkerTable.reset", false]], "root_dir (odatse.domain._domain.domainbase attribute)": [[16, "odatse.domain._domain.DomainBase.root_dir", false]], "rosenbrock() (in module odatse.solver.analytical)": [[23, "odatse.solver.analytical.rosenbrock", false]], "run() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.run", false]], "run() (odatse.solver.function.solver method)": [[24, "odatse.solver.function.Solver.run", false]], "sample() (odatse.util.resampling.binarysearch method)": [[32, "odatse.util.resampling.BinarySearch.sample", false]], "sample() (odatse.util.resampling.walkertable method)": [[32, "odatse.util.resampling.WalkerTable.sample", false]], "score (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.score", false]], "separatet() (in module odatse.util.separatet)": [[33, "odatse.util.separateT.separateT", false]], "set_function() (odatse.solver.function.solver method)": [[24, "odatse.solver.function.Solver.set_function", false]], "set_runner() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.set_runner", false]], "solver (class in odatse.solver.analytical)": [[23, "odatse.solver.analytical.Solver", false]], "solver (class in odatse.solver.function)": [[24, "odatse.solver.function.Solver", false]], "solverbase (class in odatse.solver._solver)": [[22, "odatse.solver._solver.SolverBase", false]], "step (odatse.util.separatet.entry attribute)": [[33, "odatse.util.separateT.Entry.step", false]], "store_file() (odatse.domain.meshgrid.meshgrid method)": [[17, "odatse.domain.meshgrid.MeshGrid.store_file", false]], "t2rep (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.T2rep", false]], "tindex (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.Tindex", false]], "tindex (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.Tindex", false]], "tindex (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.Tindex", false]], "trivialmapping (class in odatse.util.mapping)": [[29, "odatse.util.mapping.TrivialMapping", false]], "ts (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.Ts", false]], "unit_list (odatse.domain.region.region attribute)": [[18, "odatse.domain.region.Region.unit_list", false]], "unlimited (class in odatse.util.limitation)": [[27, "odatse.util.limitation.Unlimited", false]], "walker (odatse.util.separatet.entry attribute)": [[33, "odatse.util.separateT.Entry.walker", false]], "walkertable (class in odatse.util.resampling)": [[32, "odatse.util.resampling.WalkerTable", false]], "write() (odatse.util.logger.logger method)": [[28, "odatse.util.logger.Logger.write", false]], "write_neighbor_list() (in module odatse.util.neighborlist)": [[30, "odatse.util.neighborlist.write_neighbor_list", false]], "write_timer() (odatse.algorithm._algorithm.algorithmbase method)": [[8, "odatse.algorithm._algorithm.AlgorithmBase.write_timer", false]], "x (odatse.algorithm.exchange.algorithm attribute)": [[10, "odatse.algorithm.exchange.Algorithm.x", false]], "x (odatse.algorithm.montecarlo.algorithmbase attribute)": [[13, "odatse.algorithm.montecarlo.AlgorithmBase.x", false]], "x (odatse.algorithm.pamc.algorithm attribute)": [[14, "odatse.algorithm.pamc.Algorithm.x", false]], "xopt (odatse.algorithm.bayes.algorithm attribute)": [[9, "odatse.algorithm.bayes.Algorithm.xopt", false]], "xs (odatse.util.separatet.entry attribute)": [[33, "odatse.util.separateT.Entry.xs", false]]}, "objects": {"": [[2, 0, 0, "-", "odatse"]], "odatse": [[3, 0, 0, "-", "_info"], [4, 0, 0, "-", "_initialize"], [5, 0, 0, "-", "_main"], [6, 0, 0, "-", "_runner"], [7, 0, 0, "-", "algorithm"], [15, 0, 0, "-", "domain"], [19, 0, 0, "-", "exception"], [20, 0, 0, "-", "mpi"], [21, 0, 0, "-", "solver"], [25, 0, 0, "-", "util"]], "odatse._info": [[3, 1, 1, "", "Info"]], "odatse._info.Info": [[3, 2, 1, "", "__init__"], [3, 2, 1, "", "_cleanup"], [3, 2, 1, "", "from_dict"], [3, 2, 1, "", "from_file"]], "odatse._initialize": [[4, 3, 1, "", "initialize"]], "odatse._main": [[5, 3, 1, "", "main"]], "odatse.algorithm": [[8, 0, 0, "-", "_algorithm"], [9, 0, 0, "-", "bayes"], [7, 3, 1, "", "choose_algorithm"], [10, 0, 0, "-", "exchange"], [11, 0, 0, "-", "mapper_mpi"], [12, 0, 0, "-", "min_search"], [13, 0, 0, "-", "montecarlo"], [14, 0, 0, "-", "pamc"]], "odatse.algorithm._algorithm": [[8, 1, 1, "", "AlgorithmBase"], [8, 1, 1, "", "AlgorithmStatus"], [8, 3, 1, "", "flatten_dict"]], "odatse.algorithm._algorithm.AlgorithmBase": [[8, 2, 1, "", "__init__"], [8, 2, 1, "", "__init_rng"], [8, 2, 1, "", "_check_parameters"], [8, 2, 1, "", "_load_data"], [8, 2, 1, "", "_post"], [8, 2, 1, "", "_prepare"], [8, 2, 1, "", "_run"], [8, 2, 1, "", "_save_data"], [8, 2, 1, "", "_show_parameters"], [8, 2, 1, "", "main"], [8, 2, 1, "", "post"], [8, 2, 1, "", "prepare"], [8, 2, 1, "", "run"], [8, 2, 1, "", "set_runner"], [8, 2, 1, "", "write_timer"]], "odatse.algorithm.bayes": [[9, 1, 1, "", "Algorithm"]], "odatse.algorithm.bayes.Algorithm": [[9, 2, 1, "", "__init__"], [9, 2, 1, "", "_initialize"], [9, 2, 1, "", "_load_state"], [9, 2, 1, "", "_post"], [9, 2, 1, "", "_prepare"], [9, 2, 1, "", "_run"], [9, 2, 1, "", "_save_state"], [9, 4, 1, "", "bayes_max_num_probes"], [9, 4, 1, "", "best_action"], [9, 4, 1, "", "best_fx"], [9, 4, 1, "", "fx_list"], [9, 4, 1, "", "interval"], [9, 4, 1, "", "label_list"], [9, 4, 1, "", "mesh_list"], [9, 4, 1, "", "num_rand_basis"], [9, 4, 1, "", "param_list"], [9, 4, 1, "", "random_max_num_probes"], [9, 4, 1, "", "score"], [9, 4, 1, "", "xopt"]], "odatse.algorithm.exchange": [[10, 1, 1, "", "Algorithm"]], "odatse.algorithm.exchange.Algorithm": [[10, 4, 1, "", "T2rep"], [10, 4, 1, "", "Tindex"], [10, 2, 1, "", "__exchange_multi_walker"], [10, 2, 1, "", "__exchange_single_walker"], [10, 2, 1, "", "__init__"], [10, 2, 1, "", "_exchange"], [10, 2, 1, "", "_initialize"], [10, 2, 1, "", "_load_state"], [10, 2, 1, "", "_post"], [10, 2, 1, "", "_prepare"], [10, 2, 1, "", "_print_info"], [10, 2, 1, "", "_run"], [10, 2, 1, "", "_save_state"], [10, 4, 1, "", "best_fx"], [10, 4, 1, "", "best_istep"], [10, 4, 1, "", "best_x"], [10, 4, 1, "", "exchange_direction"], [10, 4, 1, "", "fx"], [10, 4, 1, "", "inode"], [10, 4, 1, "", "istep"], [10, 4, 1, "", "nreplica"], [10, 4, 1, "", "rep2T"], [10, 4, 1, "", "x"]], "odatse.algorithm.mapper_mpi": [[11, 1, 1, "", "Algorithm"]], "odatse.algorithm.mapper_mpi.Algorithm": [[11, 2, 1, "", "__init__"], [11, 2, 1, "", "_initialize"], [11, 2, 1, "", "_load_state"], [11, 2, 1, "", "_output_results"], [11, 2, 1, "", "_post"], [11, 2, 1, "", "_prepare"], [11, 2, 1, "", "_run"], [11, 2, 1, "", "_save_state"]], "odatse.algorithm.min_search": [[12, 1, 1, "", "Algorithm"]], "odatse.algorithm.min_search.Algorithm": [[12, 2, 1, "", "__init__"], [12, 2, 1, "", "_output_results"], [12, 2, 1, "", "_post"], [12, 2, 1, "", "_prepare"], [12, 2, 1, "", "_run"]], "odatse.algorithm.montecarlo": [[13, 1, 1, "", "AlgorithmBase"], [13, 3, 1, "", "read_Ts"]], "odatse.algorithm.montecarlo.AlgorithmBase": [[13, 4, 1, "", "Tindex"], [13, 4, 1, "", "Ts"], [13, 2, 1, "", "__init__"], [13, 2, 1, "", "_evaluate"], [13, 2, 1, "", "_initialize"], [13, 2, 1, "", "_setup_neighbour"], [13, 2, 1, "", "_write_result"], [13, 2, 1, "", "_write_result_header"], [13, 4, 1, "", "best_fx"], [13, 4, 1, "", "best_istep"], [13, 4, 1, "", "best_iwalker"], [13, 4, 1, "", "best_x"], [13, 4, 1, "", "comm"], [13, 4, 1, "", "fx"], [13, 4, 1, "", "istep"], [13, 2, 1, "", "local_update"], [13, 4, 1, "", "nwalkers"], [13, 2, 1, "", "propose"], [13, 4, 1, "", "rank"], [13, 4, 1, "", "x"]], "odatse.algorithm.pamc": [[14, 1, 1, "", "Algorithm"]], "odatse.algorithm.pamc.Algorithm": [[14, 4, 1, "", "Tindex"], [14, 2, 1, "", "__init__"], [14, 2, 1, "", "_find_scheduling"], [14, 2, 1, "", "_gather_information"], [14, 2, 1, "", "_initialize"], [14, 2, 1, "", "_load_state"], [14, 2, 1, "", "_post"], [14, 2, 1, "", "_prepare"], [14, 2, 1, "", "_resample"], [14, 2, 1, "", "_resample_fixed"], [14, 2, 1, "", "_resample_varied"], [14, 2, 1, "", "_run"], [14, 2, 1, "", "_save_state"], [14, 2, 1, "", "_save_stats"], [14, 4, 1, "", "best_fx"], [14, 4, 1, "", "best_istep"], [14, 4, 1, "", "best_x"], [14, 4, 1, "", "betas"], [14, 4, 1, "", "comm"], [14, 4, 1, "", "fx"], [14, 4, 1, "", "istep"], [14, 4, 1, "", "logweights"], [14, 4, 1, "", "nreplica"], [14, 4, 1, "", "rank"], [14, 4, 1, "", "x"]], "odatse.domain": [[16, 0, 0, "-", "_domain"], [17, 0, 0, "-", "meshgrid"], [18, 0, 0, "-", "region"]], "odatse.domain._domain": [[16, 1, 1, "", "DomainBase"]], "odatse.domain._domain.DomainBase": [[16, 2, 1, "", "__init__"], [16, 4, 1, "", "mpirank"], [16, 4, 1, "", "mpisize"], [16, 4, 1, "", "output_dir"], [16, 4, 1, "", "root_dir"]], "odatse.domain.meshgrid": [[17, 1, 1, "", "MeshGrid"]], "odatse.domain.meshgrid.MeshGrid": [[17, 2, 1, "", "__init__"], [17, 2, 1, "", "_setup"], [17, 2, 1, "", "_setup_from_file"], [17, 2, 1, "", "_setup_grid"], [17, 2, 1, "", "do_split"], [17, 2, 1, "", "from_dict"], [17, 2, 1, "", "from_file"], [17, 2, 1, "", "store_file"]], "odatse.domain.region": [[18, 1, 1, "", "Region"]], "odatse.domain.region.Region": [[18, 2, 1, "", "__init__"], [18, 2, 1, "", "_init_random"], [18, 2, 1, "", "_setup"], [18, 4, 1, "", "initial_list"], [18, 2, 1, "", "initialize"], [18, 4, 1, "", "max_list"], [18, 4, 1, "", "min_list"], [18, 4, 1, "", "unit_list"]], "odatse.exception": [[19, 5, 1, "", "Error"], [19, 5, 1, "", "InputError"]], "odatse.solver": [[22, 0, 0, "-", "_solver"], [23, 0, 0, "-", "analytical"], [24, 0, 0, "-", "function"]], "odatse.solver._solver": [[22, 1, 1, "", "SolverBase"]], "odatse.solver._solver.SolverBase": [[22, 2, 1, "", "__init__"], [22, 2, 1, "", "evaluate"], [22, 6, 1, "", "name"]], "odatse.solver.analytical": [[23, 1, 1, "", "Solver"], [23, 3, 1, "", "ackley"], [23, 3, 1, "", "himmelblau"], [23, 3, 1, "", "linear_regression_test"], [23, 3, 1, "", "quadratics"], [23, 3, 1, "", "quartics"], [23, 3, 1, "", "rosenbrock"]], "odatse.solver.analytical.Solver": [[23, 2, 1, "", "__init__"]], "odatse.solver.function": [[24, 1, 1, "", "Solver"]], "odatse.solver.function.Solver": [[24, 2, 1, "", "__init__"], [24, 2, 1, "", "evaluate"], [24, 2, 1, "", "get_results"], [24, 2, 1, "", "prepare"], [24, 2, 1, "", "run"], [24, 2, 1, "", "set_function"]], "odatse.util": [[26, 0, 0, "-", "graph"], [27, 0, 0, "-", "limitation"], [28, 0, 0, "-", "logger"], [29, 0, 0, "-", "mapping"], [30, 0, 0, "-", "neighborlist"], [31, 0, 0, "-", "read_matrix"], [32, 0, 0, "-", "resampling"], [33, 0, 0, "-", "separateT"], [34, 0, 0, "-", "toml"]], "odatse.util.graph": [[26, 3, 1, "", "is_bidirectional"], [26, 3, 1, "", "is_connected"]], "odatse.util.limitation": [[27, 1, 1, "", "Inequality"], [27, 1, 1, "", "LimitationBase"], [27, 1, 1, "", "Unlimited"]], "odatse.util.limitation.Inequality": [[27, 2, 1, "", "__init__"], [27, 2, 1, "", "from_dict"], [27, 2, 1, "", "judge"]], "odatse.util.limitation.LimitationBase": [[27, 2, 1, "", "__init__"], [27, 2, 1, "", "judge"]], "odatse.util.limitation.Unlimited": [[27, 2, 1, "", "__init__"], [27, 2, 1, "", "judge"]], "odatse.util.logger": [[28, 1, 1, "", "Logger"]], "odatse.util.logger.Logger": [[28, 2, 1, "", "__init__"], [28, 2, 1, "", "count"], [28, 2, 1, "", "is_active"], [28, 2, 1, "", "prepare"], [28, 2, 1, "", "write"]], "odatse.util.mapping": [[29, 1, 1, "", "Affine"], [29, 1, 1, "", "MappingBase"], [29, 1, 1, "", "TrivialMapping"]], "odatse.util.mapping.Affine": [[29, 2, 1, "", "__init__"], [29, 2, 1, "", "from_dict"]], "odatse.util.neighborlist": [[30, 1, 1, "", "Cells"], [30, 3, 1, "", "load_neighbor_list"], [30, 3, 1, "", "make_neighbor_list"], [30, 3, 1, "", "make_neighbor_list_cell"], [30, 3, 1, "", "make_neighbor_list_naive"], [30, 3, 1, "", "write_neighbor_list"]], "odatse.util.neighborlist.Cells": [[30, 2, 1, "", "__init__"], [30, 2, 1, "", "cellcoord2cellindex"], [30, 2, 1, "", "cellindex2cellcoord"], [30, 2, 1, "", "coord2cellcoord"], [30, 2, 1, "", "coord2cellindex"], [30, 2, 1, "", "neighborcells"], [30, 2, 1, "", "out_of_bound"]], "odatse.util.read_matrix": [[31, 3, 1, "", "read_matrix"], [31, 3, 1, "", "read_vector"]], "odatse.util.resampling": [[32, 1, 1, "", "BinarySearch"], [32, 1, 1, "", "Resampler"], [32, 1, 1, "", "WalkerTable"]], "odatse.util.resampling.BinarySearch": [[32, 2, 1, "", "__init__"], [32, 2, 1, "", "_sample"], [32, 2, 1, "", "reset"], [32, 2, 1, "", "sample"]], "odatse.util.resampling.WalkerTable": [[32, 2, 1, "", "__init__"], [32, 2, 1, "", "_sample"], [32, 2, 1, "", "reset"], [32, 2, 1, "", "sample"]], "odatse.util.separateT": [[33, 1, 1, "", "Entry"], [33, 3, 1, "", "separateT"]], "odatse.util.separateT.Entry": [[33, 2, 1, "", "_asdict"], [33, 2, 1, "", "_make"], [33, 2, 1, "", "_replace"], [33, 4, 1, "", "fx"], [33, 4, 1, "", "step"], [33, 4, 1, "", "walker"], [33, 4, 1, "", "xs"]], "odatse.util.toml": [[34, 3, 1, "", "load"]]}, "objnames": {"0": ["py", "module", "Python module"], "1": ["py", "class", "Python class"], "2": ["py", "method", "Python method"], "3": ["py", "function", "Python function"], "4": ["py", "attribute", "Python attribute"], "5": ["py", "exception", "Python exception"], "6": ["py", "property", "Python property"]}, "objtypes": {"0": "py:module", "1": "py:class", "2": "py:method", "3": "py:function", "4": "py:attribute", "5": "py:exception", "6": "py:property"}, "terms": {"": [13, 23, 32], "0": [23, 28, 33], "005071": 23, "1": [8, 13, 18, 22, 23, 24, 33], "10": 18, "100": 18, "10000": 33, "11": 18, "131312": 23, "2": [23, 33], "2831860": 23, "2d": 5, "2dmat": [16, 22], "3": [8, 18, 23, 33], "4": 23, "5": 23, "584428": 23, "6": 23, "628571": 23, "664976": 23, "779310": 23, "8": 23, "805118": 23, "848126": 23, "A": [3, 9, 18, 26, 29, 30, 31, 32], "If": [3, 13, 24, 30, 31, 32], "It": [5, 14, 23], "The": [3, 9, 10, 11, 14, 16, 22, 23, 30, 32], "__exchange_multi_walk": 10, "__exchange_single_walk": 10, "__init__": [3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 27, 28, 29, 30, 32], "__init_rng": 8, "_algorithm": 7, "_asdict": 33, "_check_paramet": 8, "_cleanup": 3, "_domain": 15, "_evalu": 13, "_exchang": 10, "_find_schedul": 14, "_gather_inform": 14, "_info": [0, 2], "_init_random": 18, "_initi": [0, 2, 9, 10, 11, 13, 14], "_load_data": 8, "_load_stat": [9, 10, 11, 14], "_main": [0, 2], "_make": 33, "_output_result": [11, 12], "_post": [8, 9, 10, 11, 12, 14], "_prepar": [8, 9, 10, 11, 12, 14], "_print_info": 10, "_replac": 33, "_resampl": 14, "_resample_fix": 14, "_resample_vari": 14, "_run": [8, 9, 10, 11, 12, 14], "_runner": [0, 2], "_sampl": 32, "_save_data": 8, "_save_st": [9, 10, 11, 14], "_save_stat": 14, "_setup": [17, 18], "_setup_from_fil": 17, "_setup_grid": 17, "_setup_neighbour": 13, "_show_paramet": 8, "_solver": 21, "_write_result": 13, "_write_result_head": 13, "abc": 32, "about": 10, "abstract": [8, 14, 22, 27], "accept": [13, 14], "acceptance_ratio": 14, "accordingli": 14, "acklei": 23, "across": 14, "action": 9, "activ": [27, 28], "addit": [3, 13, 22, 24, 28], "affin": 29, "after": [8, 12, 14], "against": 8, "algorithm": [0, 2, 5, 17, 18], "algorithmbas": [8, 9, 10, 11, 12, 13, 14], "algorithmstatu": 8, "alia": [32, 33], "all": [9, 11, 13, 14, 30], "allow": 30, "allow_selfloop": 30, "also": 14, "alwai": 27, "among": 17, "an": [3, 4, 16, 27, 29, 31, 32, 34], "analysi": [3, 5, 11], "analyt": 21, "ancestor": 14, "ani": [3, 17, 18, 28, 34], "anneal": 14, "approach": 30, "appropri": 5, "ar": [13, 23, 30, 33], "arbitrari": 23, "arg": [22, 24, 28], "argument": [3, 4, 5, 22, 24, 28], "arrai": [13, 14, 18, 22, 23, 24, 27, 29, 31, 32, 33], "as_beta": 13, "attribut": 9, "ax": 23, "b": [23, 27, 29], "balanc": 14, "bar": 30, "base": [3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 22, 23, 24, 27, 28, 29, 30, 32, 33], "basi": 9, "bay": 7, "bayes_max_num_prob": 9, "bayesian": 9, "beam": [5, 11, 17, 33], "befor": 28, "benchmark": 23, "best": [9, 10, 13, 14], "best_act": 9, "best_fx": [9, 10, 13, 14], "best_istep": [10, 13, 14], "best_iwalk": 13, "best_result": 14, "best_x": [10, 13, 14], "beta": [13, 14, 33], "between": 8, "bidirect": [13, 26], "binari": 32, "binarysearch": 32, "bmax": 13, "bmin": 13, "bool": [9, 10, 11, 13, 14, 26, 27, 28, 30, 33], "boolean": 27, "both": 13, "bound": 30, "boundari": 8, "buffer": [28, 33], "buffer_s": [28, 33], "calcul": [10, 13, 14, 23], "call": 28, "callabl": 24, "can": 14, "candid": 13, "carlo": [10, 13, 14], "cell": 30, "cellcoord2cellindex": 30, "cellindex2cellcoord": 30, "cellsiz": 30, "check": [8, 26, 28, 30], "check_allpair": 30, "choose_algorithm": 7, "class": [3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 22, 23, 24, 27, 28, 29, 30, 32, 33], "classmethod": [3, 17, 27, 29, 33], "co_a": 27, "co_b": 27, "coeffici": 27, "colormap": 11, "column": 13, "comm": [13, 14, 30, 33], "command": 5, "commandlin": 4, "common": 8, "commun": [13, 14, 16, 30, 33], "condit": 27, "configur": [10, 13, 14, 22, 23, 24], "connect": [13, 26], "consid": 30, "consolid": 14, "constant": 27, "construct": 9, "contain": [3, 8, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 27, 28, 29, 30], "continu": 14, "convert": [30, 31], "coord2cellcoord": 30, "coord2cellindex": 30, "coordin": 30, "correspond": [14, 23, 32], "count": 28, "counter": [13, 14], "creat": [3, 17, 27, 28, 29, 30, 33], "current": [9, 10, 11, 13, 14], "d": [3, 8, 13, 27, 29], "data": [3, 5, 8, 11, 14, 17, 22, 28, 31, 33], "dataset": 14, "default": [3, 8, 9, 10, 11, 13, 14, 22, 30, 33], "defin": [12, 13, 23, 29], "detail": 22, "determin": [14, 30, 33], "dict": [8, 11, 13, 14, 17, 18, 28, 29, 33], "dictionari": [3, 8, 11, 13, 14, 17, 18, 27, 29, 34], "differ": 14, "diffract": [5, 11, 17, 33], "dimens": [13, 18, 23], "direct": 10, "directori": [16, 28, 33], "discret": [10, 13], "do_split": 17, "domain": [0, 2, 9, 11, 12, 13], "domainbas": [16, 17, 18], "e": 13, "each": [13, 14, 18, 26, 30], "either": [14, 31], "elaps": 28, "energi": [10, 13, 14], "ensur": 14, "entri": [28, 33], "enumer": 8, "error": 19, "evalu": [13, 22, 24], "except": [0, 2, 3], "exchang": 7, "exchange_direct": 10, "execut": [5, 8, 9, 10, 11, 13, 14], "experi": [5, 11, 17, 33], "explan": 19, "extra": 13, "extra_info_to_writ": 13, "extra_nam": 13, "f": [23, 24], "factor": 14, "fals": [13, 26, 28, 30], "field": 33, "file": [3, 4, 5, 8, 9, 10, 11, 12, 13, 14, 17, 28, 30, 33, 34], "file_nam": 3, "file_result": 13, "file_tri": 13, "filenam": [8, 9, 10, 11, 14, 28, 30], "final": 9, "find": 32, "fix": 14, "flag": [28, 33], "flatten": 8, "flatten_dict": 8, "float": [9, 10, 13, 14, 23, 24, 28, 30, 31, 32], "fmt": 3, "follow": [14, 23], "format": 3, "four": 23, "fp": 13, "from": [3, 8, 9, 10, 11, 13, 14, 17, 18, 27, 29, 30, 33], "from_dict": [3, 17, 27, 29], "from_fil": [3, 17], "function": [4, 5, 8, 9, 14, 21, 23], "fx": [10, 13, 14, 33], "fx_list": 9, "g": 13, "gather": [11, 14], "gaussian": 23, "gener": [8, 9, 10, 11, 13, 14, 18, 32], "get": [22, 24, 30], "get_result": 24, "given": [8, 18, 22, 24, 30, 32], "global": 23, "graph": [13, 25], "grid": [9, 17, 30], "ha": [8, 23], "handl": [17, 28], "have": 4, "header": [13, 17], "himmelblau": 23, "hostedtoolcach": 18, "i": [3, 9, 13, 14, 24, 26, 27, 28, 31, 32, 33], "implement": [8, 14, 22], "in_rang": 13, "includ": [13, 14, 17], "index": [0, 10, 13, 14, 30, 32], "indic": [13, 27, 28, 30, 32], "inequ": 27, "info": [3, 4, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 28], "info_pamc": 14, "info_param": [13, 17, 18], "inform": [3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 28], "inherit": 11, "initi": [3, 4, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 27, 28, 29, 30, 32], "initial_list": 18, "inod": 10, "inp": 31, "input": [3, 4, 5, 14, 19, 22, 23, 24, 27, 28, 29, 31, 33, 34], "inputerror": [3, 19], "instanc": [11, 16, 27, 29, 33], "instead": 33, "int": [8, 9, 10, 13, 14, 16, 18, 22, 24, 26, 28, 30, 32, 33], "intenum": 8, "interv": 9, "invalid": 13, "invers": [13, 14], "is_act": 28, "is_bidirect": 26, "is_connect": 26, "is_limitari": 27, "istep": [10, 13, 14], "iter": [32, 33], "its": 3, "jarzynski": 14, "job": 12, "judg": [18, 27], "kei": [8, 14, 27, 29], "keyword": [3, 28], "kwarg": 3, "kwd": 33, "label": 9, "label_list": 9, "lib": 18, "likelihood": 23, "limit": [18, 25], "limitationbas": 27, "line": 5, "linear": 23, "linear_regression_test": 23, "list": [9, 13, 14, 17, 26, 30, 31], "load": [3, 4, 5, 8, 9, 10, 11, 14, 30, 34], "load_neighbor_list": 30, "local": 23, "local_upd": 13, "log": [13, 14, 23, 28], "logarithm": 14, "logger": 25, "logweight": 14, "loop": 30, "made": 13, "main": [4, 5, 8, 11], "maintain": 14, "make": 33, "make_neighbor_list": 30, "make_neighbor_list_cel": 30, "make_neighbor_list_na": 30, "manag": 16, "mani": 23, "map": [10, 25, 33], "mapper_mpi": 7, "mappingbas": 29, "materi": 5, "matrix": [27, 29, 31], "max": [17, 30], "max_count": 18, "max_list": 18, "maximum": [9, 18, 30, 32], "mead": 12, "mesh": 9, "mesh_list": 9, "mesh_path": 17, "meshgrid": [11, 15], "messag": 19, "method": [8, 9, 12, 13, 14, 22, 27, 32], "min": [17, 30], "min_list": 18, "min_search": 7, "minim": 12, "minima": 23, "minimum": [18, 23, 30], "miss": 3, "mode": [8, 9, 10, 11, 12, 13, 14], "model": 23, "modul": [0, 2, 7, 15, 21, 25], "mont": [10, 13, 14], "montecarlo": 7, "mpi": [0, 2, 11, 13, 14, 16, 17, 30, 33], "mpirank": 16, "mpisiz": 16, "multipl": 10, "mutablemap": [3, 34], "n": [13, 14, 23, 30], "naiv": 30, "name": [3, 7, 8, 9, 10, 11, 13, 14, 22, 28, 33], "ndarrai": [9, 10, 13, 14, 22, 23, 24, 27, 28, 29, 30, 31, 32, 33], "neal": 14, "necessari": 9, "neg": 23, "neighbor": [13, 26, 30], "neighborcel": 30, "neighborhood": 30, "neighborlist": 25, "neither": 13, "nelder": 12, "nest": 8, "new": [13, 32, 33], "next": 13, "ngen": 8, "nnlist": [26, 30], "nnode": 30, "node": [26, 30], "nois": 23, "none": [3, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 28, 29, 30, 32, 33], "nor": 13, "note": 23, "notimplementederror": 22, "np": [9, 10, 13, 14, 18, 22, 23, 24, 27, 28, 29, 30, 31, 32, 33], "nproc": [22, 24], "nreplica": [10, 14], "nt": 22, "nthread": [22, 24], "num": 17, "num_rand_basi": 9, "num_walk": 18, "number": [8, 9, 10, 11, 13, 14, 18, 22, 24, 30, 31, 32, 33], "numpi": [18, 31], "numt": [13, 14], "nwalker": [13, 33], "nxd": 13, "object": [3, 4, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 22, 23, 24, 27, 28, 29, 30, 33], "odats": 0, "offset": 14, "one": [13, 23], "oper": [11, 29, 32], "opt": 18, "optim": 9, "option": [3, 8, 9, 10, 11, 13, 14, 16, 17, 18, 22, 24, 28, 29, 30, 33], "origin": 14, "otherwis": [26, 28, 30], "out": 30, "out_of_bound": 30, "output": [11, 12, 16, 30, 33], "output_dir": [16, 33], "over": 14, "overwrit": 13, "packag": [0, 1, 18], "page": 0, "pair": 30, "pamc": 7, "parallel": 33, "param": [8, 17, 18, 28], "param_list": 9, "paramet": [3, 4, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 22, 23, 24, 26, 27, 28, 29, 30, 31, 32, 33, 34], "parent": 8, "parent_kei": 8, "pariti": 10, "pars": [4, 5], "partit": 30, "path": [8, 13, 16, 17, 28, 30, 34], "pathlik": [30, 33], "per": 13, "perform": [8, 12, 14, 32], "phase": 14, "pickl": 8, "point": [13, 23, 30], "pointer": 13, "popul": 14, "posit": [13, 14], "post": [8, 10, 11, 12, 14], "pre": 23, "predefin": 18, "prepar": [8, 9, 10, 11, 12, 14, 24, 28], "previou": 8, "print": 10, "probe": 9, "problem": 13, "proc": [10, 14], "proc_dir": 28, "process": [8, 9, 10, 11, 12, 13, 14, 16, 17, 22, 24, 33], "progress": 30, "properti": 22, "propos": 13, "provid": [8, 13, 14, 17], "py": 18, "python": 18, "python3": 18, "quadrat": 23, "qualnam": 8, "quantum": [5, 11, 17, 33], "quartic": 23, "r": 32, "radiu": 30, "rais": [3, 13, 19, 22, 24, 31], "random": [8, 9, 10, 11, 14, 18, 32], "random_max_num_prob": 9, "randomst": 32, "rang": 13, "rank": [11, 13, 14, 16], "ratio": 14, "re": 14, "read": [13, 33, 34], "read_matrix": 25, "read_t": 13, "read_vector": 31, "region": 15, "regress": 23, "rep2t": 10, "replac": 33, "replica": [10, 14], "repres": [3, 9, 18, 26, 27, 30, 31, 34], "requir": 3, "resampl": [14, 25], "reset": [3, 13, 14, 32], "rest": 28, "restor": [9, 10, 11, 14], "restore_rng": [9, 10, 11, 14], "result": [8, 9, 10, 11, 12, 13, 14, 24, 28], "resum": [9, 10, 14], "return": [3, 4, 7, 8, 11, 13, 14, 17, 22, 23, 24, 26, 27, 28, 29, 30, 31, 32, 33, 34], "revers": 10, "rng": 18, "root": 16, "root_dir": 16, "rosenbrock": 23, "row": 31, "run": [5, 8, 9, 10, 11, 12, 13, 14, 24], "run_mod": [4, 8, 9, 10, 11, 12, 13, 14], "runner": [8, 9, 10, 11, 12, 13, 14, 28], "runtimeerror": [13, 24, 31], "saddl": 23, "sampl": [13, 32], "satisfi": 27, "save": [8, 9, 10, 11, 14], "scale": 32, "schedul": 14, "score": 9, "search": [0, 7, 12, 32], "section": 3, "select": 5, "self": [13, 30], "separ": [8, 31, 33], "separatet": 25, "sequenc": [13, 33], "set": [8, 12, 13, 14, 17, 24], "set_b": 13, "set_funct": 24, "set_runn": 8, "set_t": 13, "setup": [17, 18], "shape": 23, "should": [8, 22, 28], "show": [8, 30], "show_progress": 30, "sigma": 23, "simplex": 12, "singl": [10, 14, 32], "site": 18, "size": [14, 16, 28, 30, 32, 33], "softwar": [3, 5, 16, 22], "solut": 9, "solver": [0, 2, 5], "solverbas": [22, 24], "sourc": [3, 4, 5, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 22, 23, 24, 26, 27, 28, 29, 30, 31, 32, 33, 34], "space": [10, 12, 13, 31], "spatial": 30, "specifi": [13, 18, 33], "sphere": 23, "split": 17, "start": 8, "state": [3, 8, 9, 10, 11, 13, 14, 32], "statist": 14, "statu": [8, 14], "step": [8, 10, 13, 14, 33], "store": [17, 33], "store_fil": 17, "store_path": 17, "str": [3, 4, 7, 8, 9, 10, 11, 12, 13, 14, 17, 18, 19, 22, 28, 30, 31, 34], "string": [4, 31], "structur": [3, 5, 8], "subclass": [8, 14, 22], "sublist": 26, "submit": [11, 12, 14], "submodul": 0, "subpackag": 0, "t": [13, 33], "t2rep": 10, "task": 11, "temperatur": [10, 13, 14, 33], "textio": 13, "them": 14, "thi": [13, 14, 22], "thread": [22, 24], "time": [8, 28], "timer": [9, 11, 14], "tindex": [10, 13, 14], "tmax": 13, "tmin": 13, "toml": 25, "toml_dict": 34, "train": 23, "transform": 29, "transit": 13, "translat": 29, "trial": [13, 14, 18], "trivial": 29, "trivialmap": 29, "true": [9, 10, 11, 13, 14, 26, 27, 28, 30], "try": 10, "tupl": [4, 13, 22, 24, 33], "two": 23, "txt": 14, "type": [3, 4, 7, 8, 9, 10, 11, 13, 14, 16, 17, 18, 22, 23, 24, 26, 27, 28, 29, 30, 31, 32, 34], "unchang": 29, "union": [13, 31], "unit": [18, 30], "unit_list": 18, "unknown": 13, "unlimit": [18, 27], "unsupport": 3, "up": [13, 14, 17], "updat": 14, "us": [8, 12, 13, 14, 22, 24, 30, 32, 33], "use_beta": 33, "util": [0, 2, 18], "valid": [13, 18], "valu": [4, 8, 9, 13, 14, 18, 23, 33], "valueerror": [3, 13], "vari": 14, "vector": [27, 29, 31], "version": 8, "walker": [10, 13, 14, 18, 32, 33], "walkert": 32, "weight": [14, 32], "where": [8, 14, 17, 26, 28], "whether": [9, 10, 11, 13, 14, 30], "which": [8, 14, 30, 33], "within": [13, 18, 30], "write": [8, 9, 13, 14, 28, 30], "write_input": 28, "write_neighbor_list": 30, "write_result": 28, "write_tim": 8, "written": 8, "x": [10, 13, 14, 22, 23, 24, 27, 28, 30, 33], "x64": 18, "xdata": 23, "xopt": 9, "y": 23, "ydata": 23}, "titles": ["Welcome to ODAT-SE API\u2019s documentation!", "odatse", "odatse package", "odatse._info module", "odatse._initialize module", "odatse._main module", "odatse._runner module", "odatse.algorithm package", "odatse.algorithm._algorithm module", "odatse.algorithm.bayes module", "odatse.algorithm.exchange module", "odatse.algorithm.mapper_mpi module", "odatse.algorithm.min_search module", "odatse.algorithm.montecarlo module", "odatse.algorithm.pamc module", "odatse.domain package", "odatse.domain._domain module", "odatse.domain.meshgrid module", "odatse.domain.region module", "odatse.exception module", "odatse.mpi module", "odatse.solver package", "odatse.solver._solver module", "odatse.solver.analytical module", "odatse.solver.function module", "odatse.util package", "odatse.util.graph module", "odatse.util.limitation module", "odatse.util.logger module", "odatse.util.mapping module", "odatse.util.neighborlist module", "odatse.util.read_matrix module", "odatse.util.resampling module", "odatse.util.separateT module", "odatse.util.toml module"], "titleterms": {"": 0, "_algorithm": 8, "_domain": 16, "_info": 3, "_initi": 4, "_main": 5, "_runner": 6, "_solver": 22, "algorithm": [7, 8, 9, 10, 11, 12, 13, 14], "analyt": 23, "api": 0, "bay": 9, "content": 0, "document": 0, "domain": [15, 16, 17, 18], "except": 19, "exchang": 10, "function": 24, "graph": 26, "indic": 0, "limit": 27, "logger": 28, "map": 29, "mapper_mpi": 11, "meshgrid": 17, "min_search": 12, "modul": [3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 17, 18, 19, 20, 22, 23, 24, 26, 27, 28, 29, 30, 31, 32, 33, 34], "montecarlo": 13, "mpi": 20, "neighborlist": 30, "odat": 0, "odats": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34], "packag": [2, 7, 15, 21, 25], "pamc": 14, "read_matrix": 31, "region": 18, "resampl": 32, "se": 0, "separatet": 33, "solver": [21, 22, 23, 24], "submodul": [2, 7, 15, 21, 25], "subpackag": 2, "tabl": 0, "toml": 34, "util": [25, 26, 27, 28, 29, 30, 31, 32, 33, 34], "welcom": 0}}) \ No newline at end of file diff --git a/manual/v3.0.0/en/.buildinfo b/manual/v3.0.0/en/.buildinfo new file mode 100644 index 00000000..8116d667 --- /dev/null +++ b/manual/v3.0.0/en/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 027d1cc868952cd792fd9d07ec292c2d +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/manual/v3.0.0/en/_images/plot_himmelblau.png b/manual/v3.0.0/en/_images/plot_himmelblau.png new file mode 100644 index 00000000..3c0ecf62 Binary files /dev/null and b/manual/v3.0.0/en/_images/plot_himmelblau.png differ diff --git a/manual/v3.0.0/en/_images/res_bayes_plot.png b/manual/v3.0.0/en/_images/res_bayes_plot.png new file mode 100644 index 00000000..debf1692 Binary files /dev/null and b/manual/v3.0.0/en/_images/res_bayes_plot.png differ diff --git a/manual/v3.0.0/en/_images/res_exchange.png b/manual/v3.0.0/en/_images/res_exchange.png new file mode 100644 index 00000000..2e2b588d Binary files /dev/null and b/manual/v3.0.0/en/_images/res_exchange.png differ diff --git a/manual/v3.0.0/en/_images/res_limitation.png b/manual/v3.0.0/en/_images/res_limitation.png new file mode 100644 index 00000000..78ae6a19 Binary files /dev/null and b/manual/v3.0.0/en/_images/res_limitation.png differ diff --git a/manual/v3.0.0/en/_images/res_mapper.png b/manual/v3.0.0/en/_images/res_mapper.png new file mode 100644 index 00000000..d83e464d Binary files /dev/null and b/manual/v3.0.0/en/_images/res_mapper.png differ diff --git a/manual/v3.0.0/en/_images/res_minsearch.png b/manual/v3.0.0/en/_images/res_minsearch.png new file mode 100644 index 00000000..b4a54fd1 Binary files /dev/null and b/manual/v3.0.0/en/_images/res_minsearch.png differ diff --git a/manual/v3.0.0/en/_images/res_pamc.png b/manual/v3.0.0/en/_images/res_pamc.png new file mode 100644 index 00000000..89a6fe28 Binary files /dev/null and b/manual/v3.0.0/en/_images/res_pamc.png differ diff --git a/manual/v3.0.0/en/_sources/acknowledgement.rst.txt b/manual/v3.0.0/en/_sources/acknowledgement.rst.txt new file mode 100644 index 00000000..b77425f7 --- /dev/null +++ b/manual/v3.0.0/en/_sources/acknowledgement.rst.txt @@ -0,0 +1,7 @@ +Acknowledgements +================================ + +The development of 2DMAT and ODAT-SE was supported by JSPS KAKENHI Grant Numbers 19H04125, 20H00581, 21K19773, and 23K18465, and "Project for advancement of software usability in materials science" (FY2020, 2021, and 2024) of The Institute for Solid State Physics, The University of Tokyo. + +A part of the design of and naming in software is inspired by `abics `_. +For adding a tutorial for customizing solver, we thank to K. Tsukamoto (ISSP). diff --git a/manual/v3.0.0/en/_sources/algorithm/bayes.rst.txt b/manual/v3.0.0/en/_sources/algorithm/bayes.rst.txt new file mode 100644 index 00000000..56037bf6 --- /dev/null +++ b/manual/v3.0.0/en/_sources/algorithm/bayes.rst.txt @@ -0,0 +1,197 @@ +Bayesian optimization ``bayes`` +******************************* + +.. _PHYSBO: https://www.pasums.issp.u-tokyo.ac.jp/physbo/en + +``bayes`` is an ``Algorithm`` that uses Bayesian optimization to perform parameter search. +The implementation is based on `PHYSBO`_. + +Preparation +~~~~~~~~~~~~ +You will need to install `PHYSBO`_ beforehand. + +.. code-block:: bash + + $ python3 -m pip install physbo + +If `mpi4py `_ is installed, MPI parallel computing is possible. + +.. _bayes_input: + +Input parameters +~~~~~~~~~~~~~~~~~~~~~ + +[``algorithm.param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section, the search parameter space is defined. + +If ``mesh_path`` is defined, it will be read from a mesh file. +In a mesh file, one line gives one point in the parameter space, +the first column is the data number, and the second and subsequent columns are the coordinates of each dimension. + +If ``mesh_path`` is not defined, ``min_list``, ``max_list``, and ``num_list`` are used to create an evenly spaced grid for each parameter. + +- ``mesh_path`` + + Format: String + + Description: The path to a reference file that contains information about the mesh data. + +- ``min_list`` + + Format: List of float. The length should match the value of dimension. + + Description: The minimum value the parameter can take. + +- ``max_list`` + + Format: List of float.The length should match the value of dimension. + + Description: The maximum value the parameter can take. + +- ``num_list`` + + Format: List of integer. The length should match the value of dimension. + + Description: The number of grids the parametar can take at each dimension. + + +[``algorithm.bayes``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The hyper parameters are defined. + +- ``random_max_num_probes`` + + Format: Integer (default: 20) + + Description: Number of random samples to be taken before Bayesian optimization (random sampling is needed if parameters and scores are not available at the beginning). + +- ``bayes_max_num_probes`` + + Format: Integer (default: 40) + + Description: Number of times to perform Bayesian optimization. + +- ``score`` + + Format: String (default: ``TS`` ) + + Description: Parameter to specify the score function. + ``EI`` (expected improvement), ``PI`` (probability of improvement), and ``TS`` (Thompson sampling) can be chosen. + +- ``interval`` + + Format: Integer (default: 5) + + Description: The hyperparameters are learned at each specified interval. If a negative value is specified, no hyperparameter learning will be performed. + If a value of 0 is specified, hyperparameter learning will be performed only in the first step. + +- ``num_rand_basis`` + + Format: Integer (default: 5000) + + Description: Number of basis functions; if 0 is specified, the normal Gaussian process is performed without using the Bayesian linear model. + + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables defined in ``string_list`` in the ``[solver.param]`` section. + +Below, a sample file is shown. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +Output files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``BayesData.txt`` +^^^^^^^^^^^^^^^^^^^^^^ + +At each step of the optimization process, the values of the parameters and the corresponding objective functions are listed in the order of the optimal parameters so far and the searched parameters at that step. + +.. code-block:: + + #step z1 z2 R-factor z1_action z2_action R-factor_action + 0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885 + 1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033 + 2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189 + 3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794 + ... + + +Restart +~~~~~~~~~~~~~~~~~~~~~~ +The execution mode is specified by the ``run_mode`` parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to ``--init``, ``--resume``, and ``--cont`` options of ``odatse`` command, respectively. + +- ``"initial"`` (default) + + The program is started from the initial state. + First, it performs the random sampling for the number of times specified by ``random_max_num_probes`` parameter. + Then, it performs the Bayes optimization for the number of times specified by ``bayes_max_num_probes``. + + If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions: + + #. when the random sampling is finished. + #. during the Bayesian optimization, the specified number of iteration has been done, or the specified period of time has passed. + #. at the end of the execution. + +- ``"resume"`` + + The program execution is resumed from the latest checkpoint. + The conditions such as the number of MPI processes should be kept the same. + + It is noted that the results obtaind from the resumed run from the interruption and those obtained from the uninterrupted run do not exactly match. + +- ``"continue"`` + + The program execution of the Bayes optimization is continued from the previous run. + The value of ``bayes_max_num_probes`` should be increased. The step counter is taken over. + + For example: in the first run, the calculation is carried out for 100 Bayesian optimization steps with ``bayes_max_num_probes=100``. In the next run, the calculation is continued with ``bayes_max_num_probes=200``, where the calculations from 101st step to 200th step are carried out. + + +Algorithm Description +~~~~~~~~~~~~~~~~~~~~~~ + +`Bayesian optimization (BO) `_ is an optimization algorithm that uses machine learning as an aid, and is particularly powerful when it takes a long time to evaluate the objective function. + +In BO, the objective function :math:`f(\vec{x})` is approximated by a model function (often a Gaussian process) :math:`g(\vec{x})` that is quick to evaluate and easy to optimize. +The :math:`g` is trained to reproduce well the value of the objective function :math:`\{\vec{x}_i\}_{i=1}^N` at some suitably predetermined points (training data set) :math:`\{f(\vec{x}_i)\}_{i=1}^N`. + +At each point in the parameter space, we propose the following candidate points for computation :math:`\vec{x}_{N+1}`, where the expected value of the trained :math:`g(\vec{x})` value and the "score" (acquition function) obtained from the error are optimal. +The training is done by evaluating :math:`f(\vec{x}_{N+1})`, adding it to the training dataset, and retraining :math:`g`. +After repeating these searches, the best value of the objective function as the optimal solution will be returned. + +A point that gives a better expected value with a smaller error is likely to be the correct answer, +but it does not contribute much to improving the accuracy of the model function because it is considered to already have enough information. +On the other hand, a point with a large error may not be the correct answer, +but it is a place with little information and is considered to be beneficial for updating the model function. +Selecting the former is called "exploition," while selecting the latter is called "exploration," and it is important to balance both. +The definition of "score" defines how to choose between them. + +In ODAT-SE, we use `PHYSBO`_ as a library for Bayesian optimization. +PHYSBO, like ``mapper_mpi``, computes a "score" for a predetermined set of candidate points, and proposes an optimal solution. +MPI parallel execution is possible by dividing the set of candidate points. +In addition, we use a kernel that allows us to evaluate the model function and thus calculate the "score" with a linear amount of computation with respect to the number of training data points :math:`N`. +In PHYSBO, "expected improvement (EI)", "probability of improvement (PI)", and "Thompson sampling (TS)" are available as "score" functions. + diff --git a/manual/v3.0.0/en/_sources/algorithm/exchange.rst.txt b/manual/v3.0.0/en/_sources/algorithm/exchange.rst.txt new file mode 100644 index 00000000..5ed6924e --- /dev/null +++ b/manual/v3.0.0/en/_sources/algorithm/exchange.rst.txt @@ -0,0 +1,366 @@ +Replica exchange Monte Carlo ``exchange`` +============================================= + +``exchange`` explores the parameter space by using the replica exchange Monte Carlo (RXMC) method. + +Preparation +~~~~~~~~~~~~~~~~ + +`mpi4py `_ should be installed if MPI parallelization is used. + +.. code-block:: + + $ python3 -m pip install mpi4py + +Input parameters +~~~~~~~~~~~~~~~~~~~ + +This has two subsections ``algorithm.param`` and ``algorithm.exchange`` . + +[``algorithm.param``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This defines a space to be explored. +When ``mesh_path`` key is defined the discrete space is used. +Otherwise, continuous space is used. + +- Continuous space + + - ``initial_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: Initial value of parameters. + If not defined, these will be initialize randomly. + + - ``min_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Minimum value of each parameter. + When a parameter falls below this value during the Monte Carlo search, + the solver is not evaluated and the value is considered infinite. + + + - ``max_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Maximum value of each parameter. + When a parameter exceeds this value during the Monte Carlo search, + the solver is not evaluated and the value is considered infinite. + + - ``step_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + The step length in one Monte Carlo update (deviation of Gaussian distribution). + +- Discrete space + + - ``mesh_path`` + + Format: string + + Description: Path to the mesh definition file. + + - ``neighborlist_path`` + + Format: string + + Description: Path to the neighborhood-list file. + +[``algorithm.exchange``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + Format: Integer + + Description: The number of Monte Carlo steps. + +- ``numsteps_exchange`` + + Format: Integer + + Description: The number of interval Monte Carlo steps between replica exchange. + +- ``Tmin`` + + Format: Float + + Description: The minimum value of the "temperature" (:math:`T`). + +- ``Tmax`` + + Format: Float + + Description: The maximum value of the "temperature" (:math:`T`). + +- ``bmin`` + + Format: Float + + Description: The minimum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``bmax`` + + Format: Float + + Description: The maximum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``Tlogspace`` + + Format: Boolean (default: true) + + Description: Whether to assign "temperature" to replicas equally spaced in the logarithmic space or not. + +- ``nreplica_per_proc`` + + Format: Integer (default: 1) + + Description: The number of replicas in a MPI process. + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this "algorithm". + +Below, a sample file is shown. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +Neighborhood-list file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define "neighborhoods" for each point :math:`i`, which are points that a walker can move from :math:`i` +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point :math:`i` is specified by the first column, +and the indices of final points :math:`j` are specified by the second and successive columns. + +An utility tool, ``odatse_neighborlist`` is available for generating a neighborhood-list file from a mesh file. For details, please see :doc:`../tool`. + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +Output files +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ +This file stores the suggested parameters and the corresponding value returned from the solver for each replica. +The first column is the index of the MC step. +The second column is the index of the walker in the process. +The third column is the temperature of the replica. +The fourth column is the value of the solver. +The remaining columns are the coordinates. + +Example:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861 + 2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ +This file stores the sampled parameters and the corresponding value returned from the solver for each replica. +This has the same format as ``trial.txt``. + +.. code-block:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ +The optimal value of the solver and the corresponding parameter among the all samples. + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + + +``result_T#.txt`` +^^^^^^^^^^^^^^^^^^^ +This file stores samples for each temperature ( ``#`` is replaced with the index of temperature ). +The first column is the index of the MC step. +The second column is the index of the walker. +The third column is the value of the solver. +The remaining columns are the coordinates. + +.. code-block:: + + # T = 1.0 + 0 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 1 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 2 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 3 15 28.98676409223712 3.7442621319489637 -3.868754990884034 + + +Restart +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The execution mode is specified by the ``run_mode`` parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to ``--init``, ``--resume``, and ``--cont`` options of ``odatse`` command, respectively. + +- ``"initial"`` (default) + + The program is started from the initialized state. + If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions: + + #. the specified number of steps has been done, or the specified period of time has passed. + #. at the end of the execution. + +- ``"resume"`` + + The program execution is resumed from the latest checkpoint. + The conditions such as the number of MPI processes should be kept the same. + +- ``"continue"`` + + The program execution is continued from the previous run. + The value of ``numsteps`` should be increased. The step counter is taken over. + + For example: in the first run, the calculation is carried out for 1000 steps with ``numsteps = 1000``. In the next run, the calculation is continued with ``numsteps = 2000``, where the calculations from 1001st step to 2000th step are carried out. + + +Algorithm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Markov chain Monte Carlo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Markov chain Monte Carlo (MCMC) sampling explores the parameter space by moving walkers :math:`\vec{x}` stochastically according to the weight function :math:`W(\vec{x})`. +For the weight function, the Boltzmann factor :math:`W(\vec{x}) = e^{-f(\vec{x})/T}` is generally adopted, where :math:`T>0` is the "temperature." +It is impossible in the many cases, unfortunately, to sample walkers according to :math:`W` directly. +Insteadly, the MCMC method moves walkers slightly and generates a time series :math:`\{\vec{x}_t\}` such that the distribution of the walkers obeys :math:`W` . +Let us call the transision probability from :math:`\vec{x}` to :math:`\vec{x}'` as :math:`p(\vec{x}' | \vec{x})`. +When :math:`p` is determined by the following condition ("the balance condition") + +.. math:: + + W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x}), + +the distribution of the generated time series :math:`\{\vec{x}_t\}` will converges to :math:`W(\vec{x})` [#mcmc_condition]_. +Practically, the stronger condition ("the detailed balance condition") + +.. math:: + + p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x}) + + +is usually imposed. +The detailed balance condition returns to the balance condition by taking the summation of :math:`\vec{x}`. + +ODAT-SE adopts the Metropolis-Hasting (MH) method for solving the detailed balance condition. +The MH method splits the transition process into the suggestion process and the acceptance process. + +1. Generate a candidate :math:`\vec{x}` with the suggestion probability :math:`P(\vec{x} | \vec{x}_t)`. + + - As :math:`P`, use a simple distribution such as the normal distribution with centered at x. + +2. Accept the candidate :math:`\vec{x}` with the acceptance probability :math:`Q(\vec{x} | \vec{x}_t)`. + + - If accepted, let :math:`\vec{x}_{t+1}` be `\vec{x}`. + - Otherwise, let :math:`\vec{x}_{t+1}` be `\vec{x}_t`. + +The whole transision probability is the product of these two ones, :math:`p(\vec{x} | \vec{x_t}) = P(\vec{x} | \vec{x}_t) Q(\vec{x} | \vec{x}_t)`. +The acceptance probability :math:`Q(\vec{x} | \vec{x}_t)` is defined as + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right]. + +It is easy to verify that the detailed balance condition is satisfied by substituting it into the detailed balance condition equation. + +When adopting the Boltzmann factor for the weight and a symmetry distribution +:math:`P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})` for the suggestion probability, +the acceptance probability :math:`Q` will be the following simple form: + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right]. + +By saying :math:`\Delta f = f(\vec{x}) - f(\vec{x}_t)` and using the fact :math:`Q=1` for :math:`\Delta f \le 0`, +the procedure of MCMC with the MH algorithm is the following: + +1. Choose a candidate from near the current position and calculate :math:`f` and :math:`\Delta f`. +2. If :math:`\Delta f \le 0`, that is, the walker is descending, accept it. +3. Otherwise, accept it with the probability :math:`Q=e^{-\Delta f/T}`. +4. Repeat 1-3. + +The solution is given as the point giving the minimum value of :math:`f(\vec{x})`. +The third process of the above procedure endures that walkers can climb over the hill with a height of :math:`\Delta f \sim T`, the MCMC sampling can escape from local minima. + +Replica exchange Monte Carlo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The "temperature" :math:`T` is one of the most important hyper parameters in the MCMC sampling. +The MCMC sampling can climb over the hill with a height of :math:`T` but cannot easily escape from the deeper valley than :math:`T`. +It is why we should increase the temperature in order to avoid stuck to local minima. +On the other hand, since walkers cannot see the smaller valleys than :math:`T`, the precision of the obtained result :math:`\min f(\vec{x})` becomes about :math:`T`, and it is necessary to decrease the temperature in order to achieve more precise result. +This dilemma leads us that we should tune the temperature carefully. + +One of the ways to overcome this problem is to update temperature too. +For example, simulated annealing decreases temperature as the iteration goes. +Another algorithm, simulated tempering, treats temperature as another parameter to be sampled, not a fixed hyper parameter, +and update temperature after some iterations according to the (detailed) balance condition. +Simulated tempering studies the details of a valley by cooling and escapes from a valley by heating. +Replica exchange Monte Carlo (RXMC), also known as parallel tempering, is a parallelized version of the simulated tempering. +In this algorithm, several copies of a system with different temperature, called as replicas, will be simulated in parallel. +Then, with some interval of steps, each replica exchanges temperature with another one according to the (detailed) balance condition. +As the simulated tempering does, RXMC can observe the details of a valley and escape from it by cooling and heating. +Moreover, because each temperature is assigned to just one replica, the temperature distribution will not be biased. +Using more replicas narrows the temperature interval, and increases the acceptance ratio of the temperature exchange. +This is why this algorithm suits for the massively parallel calculation. + +It is recommended that users perform ``minsearch`` optimization starting from the result of ``exchange``, because the RXMC result has uncertainty due to temperature. + +.. only:: html + + .. rubric:: footnote + +.. [#mcmc_condition] To be precisely, the non-periodicality and the ergodicity are necessary for convergence. diff --git a/manual/v3.0.0/en/_sources/algorithm/index.rst.txt b/manual/v3.0.0/en/_sources/algorithm/index.rst.txt new file mode 100644 index 00000000..5e081c5a --- /dev/null +++ b/manual/v3.0.0/en/_sources/algorithm/index.rst.txt @@ -0,0 +1,19 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Search algorithms +==================== + +ODAT-SE searches the parameter space :math:`\mathbf{X}\ni x` by using the search algorithm ``Algorithm`` and the result of ``Solver`` :math:`f(x)`. +In this section, the search algorithms implemented in ODAT-SE are described. + +.. toctree:: + :maxdepth: 1 + + minsearch + mapper_mpi + exchange + pamc + bayes diff --git a/manual/v3.0.0/en/_sources/algorithm/mapper_mpi.rst.txt b/manual/v3.0.0/en/_sources/algorithm/mapper_mpi.rst.txt new file mode 100644 index 00000000..a799f9ed --- /dev/null +++ b/manual/v3.0.0/en/_sources/algorithm/mapper_mpi.rst.txt @@ -0,0 +1,128 @@ +Direct parallel search ``mapper`` +********************************** + +``mapper_mpi`` is an algorithm to search for the minimum value by computing :math:`f(x)` on all the candidate points in the parameter space prepared in advance. +In the case of MPI execution, the set of candidate points is divided into equal parts and automatically assigned to each process to perform trivial parallel computation. + +Preparation +~~~~~~~~~~~~ + +For MPI parallelism, you need to install `mpi4py `_. + +.. code-block:: + + $ python3 -m pip install mpi4py + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _mapper_input_param: + +[``param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section, the search parameter space is defined. + +If ``mesh_path`` is defined, it is read from a mesh file. +In the mesh file, one line defines one point in the parameter space, the first column is the data number, and the second and subsequent columns are the coordinates of each dimension. + +If ``mesh_path`` is not defined, ``min_list``, ``max_list``, and ``num_list`` are used to create an evenly spaced grid for each parameter. + +- ``mesh_path`` + + Format: String + + Description: Path to the mesh definition file. + +- ``min_list`` + + Format: List of float. The length should match the value of dimension. + + Description: The minimum value the parameter can take. + +- ``max_list`` + + Format: List of float.The length should match the value of dimension. + + Description: The maximum value the parameter can take. + +- ``num_list`` + + Format: List of integer. The length should match the value of dimension. + + Description: The number of grids the parametar can take at each dimension. + + +Refernce file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +1 + ``dimension`` columns are required. +The first column is the index of the mesh, and the second and subsequent columns are the values of parameter. +The lines starting from ``#`` are ignored as comments. + +A sample file for two dimensions is shown below. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +Output file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This file contains the candidate parameters for each mesh and the function value at that time. +The mesh data is listed in the order of the variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, and the value of the function value is listed last. + +Below, output example is shown. + +.. code-block:: + + 6.000000 6.000000 0.047852 + 6.000000 5.750000 0.055011 + 6.000000 5.500000 0.053190 + 6.000000 5.250000 0.038905 + 6.000000 5.000000 0.047674 + 6.000000 4.750000 0.065919 + 6.000000 4.500000 0.053675 + 6.000000 4.250000 0.061261 + 6.000000 4.000000 0.069351 + 6.000000 3.750000 0.071868 + ... + +Restart +~~~~~~~~~~~~~~~~~~~~~~ +The execution mode is specified by the ``run_mode`` parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to ``--init``, ``--resume``, and ``--cont`` options of ``odatse`` command, respectively. + +- ``"initial"`` (default) + + The program is started from the initial state. + If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions: + + #. the specified number of grid points has been evaluated, or the specified period of time has passed. + #. at the end of the execution. + +- ``"resume"`` + + The program execution is resumed from the latest checkpoint. + The conditions such as the number of MPI processes should be kept the same. + +- ``"continue"`` + + The continue mode is not supported. diff --git a/manual/v3.0.0/en/_sources/algorithm/minsearch.rst.txt b/manual/v3.0.0/en/_sources/algorithm/minsearch.rst.txt new file mode 100644 index 00000000..df1ce989 --- /dev/null +++ b/manual/v3.0.0/en/_sources/algorithm/minsearch.rst.txt @@ -0,0 +1,147 @@ +Nelder-Mead method ``minsearch`` +******************************** + +.. _scipy.optimize.minimize: https://docs.scipy.org/doc/scipy/reference/optimize.minimize-neldermead.html + +When ``minsearch`` is selcted, the optimization by the `Nelder-Mead method `_ (a.k.a. downhill simplex method) will be done. In the Nelder-Mead method, assuming the dimension of the parameter space is :math:`D`, the optimal solution is searched by systematically moving pairs of :math:`D+1` coordinate points according to the value of the objective function at each point. + +An important hyperparameter is the initial value of the coordinates. +Although it is more stable than the simple steepest descent method, it still has the problem of being trapped in the local optimum solution, so it is recommended to repeat the calculation with different initial values several times to check the results. + +In ODAT-SE, the Scipy's function ``scipy.optimize.minimize(method="Nelder-Mead")`` is used. +For details, see `the official document `_ . + + +Preparation +~~~~~~~~~~~ + +You will need to install `scipy `_ . + +.. code-block:: + + $ python3 -m pip install scipy + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It has subsections ``param`` and ``minimize``. + +.. _minsearch_input_param: + +[``param``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``initial_list`` + + Format: List of float. The length should match the value of dimension. + + Description: Initial value of the parameter. If not defined, it will be initialized uniformly and randomly. + +- ``unit_list`` + + Format: List of float. The length should match the value of dimension. + + Description: + Units for each parameter. + In the search algorithm, each parameter is divided by each of these values to perform a simple dimensionless and normalization. + If not defined, the value is 1.0 for all dimensions. + +- ``min_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Minimum value of each parameter. + When a parameter falls below this value during the Nelson-Mead method, + the solver is not evaluated and the value is considered infinite. + +- ``max_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Maximum value of each parameter. + When a parameter exceeds this value during the Nelson-Mead method, + the solver is not evaluated and the value is considered infinite. + +[``minimize``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the hyperparameters for the Nelder-Mead method. +See the documentation of `scipy.optimize.minimize`_ for details. + +- ``initial_scale_list`` + + Format: List of float. The length should match the value of dimension. + + Description: + The difference value that is shifted from the initial value in order to create the initial simplex for the Nelder-Mead method. + The ``initial_simplex`` is given by the sum of ``initial_list`` and the dimension of the ``initial_list`` plus one component of the ``initial_scale_list``. + If not defined, scales at each dimension are set to 0.25. + +- ``xatol`` + + Format: Float (default: 1e-4) + + Description: Parameters used to determine convergence of the Nelder-Mead method. + +- ``fatol`` + + Format: Float (default: 1e-4) + + Description: Parameters used to determine convergence of the Nelder-Mead method. + +- ``maxiter`` + + Format: Integer (default: 10000) + + Description: Maximum number of iterations for the Nelder-Mead method. + +- ``maxfev`` + + Format: Integer (default: 100000) + + Description: Maximum number of times to evaluate the objective function. + + +Output files +~~~~~~~~~~~~~~~~~ + +``SimplexData.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Outputs information about the process of finding the minimum value. +The first line is a header, the second and subsequent lines are step, +the values of variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, +and finally the value of the function. + +The following is an example of the output. + +.. code-block:: + + #step z1 z2 z3 R-factor + 0 5.25 4.25 3.5 0.015199251773721183 + 1 5.25 4.25 3.5 0.015199251773721183 + 2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375 + 3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261 + 4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + 5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + +``res.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value of the final objective function and the value of the parameters at that time are described. +The objective function is listed first, followed by the values of the variables defined in ``string_list`` in the ``[solver]`` - ``[param]`` sections of the input file, in that order. + +The following is an example of the output. + +.. code-block:: + + fx = 7.382680568652868e-06 + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 + +Restart +~~~~~~~~~~~ +The restarting is not supported for the optimization by the Nelder-Mead method. diff --git a/manual/v3.0.0/en/_sources/algorithm/pamc.rst.txt b/manual/v3.0.0/en/_sources/algorithm/pamc.rst.txt new file mode 100644 index 00000000..9ed43238 --- /dev/null +++ b/manual/v3.0.0/en/_sources/algorithm/pamc.rst.txt @@ -0,0 +1,506 @@ +Population Annealing Monte Carlo ``pamc`` +=============================================== + +``pamc`` explores the parameter space by using the Population Annealing Monte Carlo (PAMC) method. + +Preparation +~~~~~~~~~~~~~~~~ + +`mpi4py `_ should be installed for the MPI parallelization. + +.. code-block:: + + $ python3 -m pip install mpi4py + +Input parameters +~~~~~~~~~~~~~~~~~~~ + +This has two subsections ``algorithm.param`` and ``algorithm.pamc`` . + +[``algorithm.param``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This defines a space to be explored. +When ``mesh_path`` key is defined the discrete space is used. +Otherwise, continuous space is used. + +- Continuous space + + - ``initial_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Initial value of parameters. + If not defined, these will be initialize randomly. + + - ``min_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Minimum value of each parameter. + When a parameter falls below this value during the Monte Carlo search, + the solver is not evaluated and the value is considered infinite. + + - ``max_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + Maximum value of each parameter. + When a parameter exceeds this value during the Monte Carlo search, + the solver is not evaluated and the value is considered infinite. + + - ``step_list`` + + Format: List of float. Length should be equal to ``dimension``. + + Description: + The step length in one Monte Carlo update (deviation of Gaussian distribution). + +- Discrete space + + - ``mesh_path`` + + Format: string + + Description: Path to the mesh definition file. + + - ``neighborlist_path`` + + Format: string + + Description: Path to the neighborhood-list file. + +[``algorithm.pamc``] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + Format: Integer + + Description: The number of Monte Carlo steps. + +- ``numsteps_annealing`` + + Format: Integer + + Description: The number of interval Monte Carlo steps between lowering "temperature". + +- ``Tnum`` + + Format: Integer + + Description: The number of "temperature" points. + +- ``Tmin`` + + Format: Float + + Description: The minimum value of the "temperature" (:math:`T`). + +- ``Tmax`` + + Format: Float + + Description: The maximum value of the "temperature" (:math:`T`). + +- ``bmin`` + + Format: Float + + Description: The minimum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``bmax`` + + Format: Float + + Description: The maximum value of the "inverse temperature" (:math:`\beta = 1/T`). + One of the "temperature" and "inverse temperature" should be defined. + +- ``Tlogspace`` + + Format: Boolean (default: true) + + Description: Whether to assign "temperature" to replicas equally spaced in the logarithmic space or not. + +- ``nreplica_per_proc`` + + Format: Integer (default: 1) + + Description: The number of replicas in a MPI process. + +- ``resampling_interval`` + + Format: Integer (default: 1) + + Description: The number of annealing processes between resampling of the replicas. + +- ``fix_num_replicas`` + + Format: Boolean (default: true) + + Description: Whether to fix the number of replicas or not on resampling. + + +About the number of steps +******************************** + +Specify just two of ``numstep``, ``numsteps_annealing``, and ``numT``. +The value of the remaining one will be determined automatically. + +Reference file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mesh definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this "algorithm". + +Below, a sample file is shown. + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +Neighborhood-list file +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define "neighborhoods" for each point :math:`i`, which are points that a walker can move from :math:`i` +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point :math:`i` is specified by the first column, +and the indices of final points :math:`j` are specified by the second and successive columns. + +An utility tool, ``odatse_neighborlist`` is available for generating a neighborhood-list file from a mesh file. For details, please see :doc:`../tool`. + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +Output files +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^ +This file stores the suggested parameters and the corresponding value returned from the solver for each temperature point (specified by ``#``). +The first column (``step``) is the index of the MC step. +The second column (``walker``) is the index of the walker in the process. +The third column (``beta``) is the inverse temperature of the replica. +The fourth column (``fx``) is the value of the solver. +The fifth - (4+dimension)-th columns are the coordinates. +The last two columns (``weight`` and ``ancestor``) are the Neal-Jarzynsky weight and the grand-ancestor of the replica. + +Example:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +This is a combination of all the ``trial_T#.txt`` in one. + +``RANK/result_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ +This file stores the sampled parameters and the corresponding value returned from the solver for each replica and each temperature. +This has the same format as ``trial.txt``. + +.. code-block:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +This is a combination of all the ``result_T#.txt`` in one. + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ +The optimal value of the solver and the corresponding parameter among the all samples. + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + + +``fx.txt`` +^^^^^^^^^^^^^^ + +This file stores statistical metrics over the all replicas for each temperature. +The first column is inverse temperature. +The second and third column are the expectation value and the standard error of the solver's output (:math:`f(x)`), respectively. +The fourth column is the number of replicas. +The fifth column is the logarithmic of the ratio between the normalization factors (partition functions) + +.. math:: + + \log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)}, + +where :math:`\beta_0` is the minimum value of :math:`\beta` used in the calculation. +The sixth column is the acceptance ratio of MC updates. + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804 + 0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058 + 0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004 + ... + +Restart +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The execution mode is specified by the ``run_mode`` parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to ``--init``, ``--resume``, and ``--cont`` options of ``odatse`` command, respectively. + +- ``"initial"`` (default) + + The program is started from the initialized state. + If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions: + + #. at the end of calculation at each temperature point, the specified number of steps has been done, or the specified period of time has passed. + #. at the end of the execution. + +- ``"resume"`` + + The program execution is resumed from the latest checkpoint. + The conditions such as the number of MPI processes should be kept the same. + +- ``"continue"`` + + The program execution is continued from the previous run. + The sequence of the temperature points should be specified so that it is continuous from that of the previous run. + + Assume that the temperature has been lowered from ``Tmax=`` :math:`T^{(1)}` to ``Tmin=`` :math:`T^{(2)}` in the previous run, the next values should be taken as ``Tmax=`` :math:`T^{(2)}` and ``Tmin=`` :math:`T^{(3)}`. + In the new calculation, the temperature points are taken from :math:`T^{(2)}` to :math:`T^{(3)}` divided by ``Tnum``, namely, :math:`T_0 = T^{(2)}`, :math:`T_1`,..., :math:`T_{\text{Tnum}-1}=T^{(3)}`. (``Tnum`` can be different from the previous run.) + + +Algorithm +~~~~~~~~~~ + +Goal +^^^^^ + +When the weight of the configuration :math:`x` under some parameter :math:`\beta_i` is given as :math:`f_i(x)` +(e.g., the Bolzmann factor :math:`f_i(x) = \exp[-\beta_i E(x)]` ), +the expectation value of :math:`A` is defined as + +.. math:: + + \langle A\rangle_i + = \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} + = \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) + = \int \mathrm{d}xA(x)\tilde{f}_i(x), + +where :math:`Z = \int \mathrm{d} x f_i(x)` is the normalization factor (partition function) +and :math:`\tilde{f}(x) = f(x)/Z` is the probability of :math:`x`. + +Our goal is to numerically calculate the expectation value for each :math:`\beta_i` and the (ratio of) the normalization factor. + +Annealed Importance Sampling (AIS) [1] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First, we introduce a series of configurations :math:`\{x_i\}` obeying the following joint probability + +.. math:: + + \tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0), + +with + +.. math:: + + \tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)}, + +where :math:`T_i(x, x')` is a transition probability from :math:`x` to :math:`x'` under :math:`\beta_i` +holding the balance condition, + +.. math:: + + + \int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x'). + +It turns out that :math:`\tilde{f}_n(x_n)` is the marginal distribution of :math:`\tilde{f}(x_0, x_1, \dots, x_n)`, that is, + +.. math:: + + + \tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n), + +from + +.. math:: + + \int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) + = \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) + = 1. + +Consequently, +:math:`\langle A \rangle_n` is represented by using the extended configuration :math:`\{x_i\}` as + +.. math:: + + + \begin{split} + \langle A \rangle_n + &\equiv + \int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n). + \end{split} + + +Unfortunately, it is difficult to generate directly a series of configurations :math:`\{x_i\}` +following the distribution :math:`\tilde{f}(x_0, x_1, \dots, x_n)`. +Then, instead of :math:`\tilde{f}(x_0, x_1, \dots, x_n)`, we consider :math:`\{x_i\}` obeying the joint distribution + +.. math:: + + \tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n), + + +by using the following the following scheme: + +1. Generete :math:`x_0` from the initial distribution :math:`\tilde{f}_0(x)` + +2. Generate :math:`x_{i+1}` from :math:`x_i` through :math:`T_{i+1}(x_i, x_{i+1})` + + +By using the reweighting method (or importance sampling method), +:math:`\langle A \rangle_n` is rewritten as + +.. math:: + + + \begin{split} + \langle A \rangle_n + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ + &= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + \end{split}. + +Because the ratio between :math:`\tilde{f}` and :math:`\tilde{g}` is + +.. math:: + + + \begin{split} + \frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \frac{f_n(x_n)}{f_0(x_0)} + \prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ + &\equiv + \frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n), + \end{split} + +the form of the expectation value will be + +.. math:: + + \langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + = \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n}. + + +Finally, the ratio between the normalization factors :math:`Z_n/Z_0` can be evaluated as + +.. math:: + + \frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n}, + +and therefore the expectation value of :math:`A` can be evaluated as a weighted arithmetic mean: + +.. math:: + + \langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}}. + +This weight :math:`w_n` is called as the Neal-Jarzynski weight. + +population annealing (PA) [2] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Although the AIS method can estimate the expectation values of :math:`A` for each parameter :math:`\beta` as the form of weighted arithmetic mean, +the variance of weights :math:`w` is generally large and then the accuracy of the result gets worse. +In order to overcome this problem, the population annealing Monte Carlo (PAMC) method resamples all the replicas according to the probability +:math:`p^{(k)} = w^{(k)} / \sum_k w^{(k)}` at some periods and resets all the weights to unity. + +The following pseudo code describes the scheme of PAMC: + +.. code-block:: python + + for k in range(K): + w[0, k] = 1.0 + x[0, k] = draw_from(β[0]) + for i in range(1, N): + for k in range(K): + w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) ) + if i % interval == 0: + x[i, :] = resample(x[i, :], w[i, :]) + w[i, :] = 1.0 + for k in range(K): + x[i, k] = transfer(x[i-1, k], β[i]) + a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:]) + +There are two resampling methods: one with a fixed number of replicas[2] and one without[3]. + +References +^^^^^^^^^^^^^ + +[1] R. M. Neal, Statistics and Computing **11**, 125-139 (2001). + +[2] K. Hukushima and Y. Iba, AIP Conf. Proc. **690**, 200 (2003). + +[3] J. Machta, Phys. Rev. E **82**, 026704 (2010). diff --git a/manual/v3.0.0/en/_sources/contact.rst.txt b/manual/v3.0.0/en/_sources/contact.rst.txt new file mode 100644 index 00000000..7b86e7a6 --- /dev/null +++ b/manual/v3.0.0/en/_sources/contact.rst.txt @@ -0,0 +1,22 @@ +Contact +========================================= + +- Bug Reports + + Please report all problems and bugs on the github `Issues `_ page. + + To resolve bugs early, follow these guidelines when reporting: + + 1. Please specify the version of ODAT-SE you are using. + + 2. If there are problems for installation, please inform us about your operating system and the compiler. + + 3. If a problem occurs during execution, enter the input file used for execution and its output. + + Thank you for your cooperation. + +- Others + + If you have any questions about your research that are difficult to consult at Issues on GitHub, please send an e-mail to the following address: + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (replace _at_ by @) diff --git a/manual/v3.0.0/en/_sources/customize/algorithm.rst.txt b/manual/v3.0.0/en/_sources/customize/algorithm.rst.txt new file mode 100644 index 00000000..174dad9a --- /dev/null +++ b/manual/v3.0.0/en/_sources/customize/algorithm.rst.txt @@ -0,0 +1,184 @@ +``Algorithm`` +================================ + +``Algorithm`` is defined as a subclass of ``odatse.algorithm.AlgorithmBase``: + +.. code-block:: python + + import odatse + + class Algorithm(odatse.algorithm.AlgorithmBase): + pass + + +``AlgorithmBase`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``AlgorithmBase`` class offers the following methods. + +- ``__init__(self, info: odatse.Info, runner: odatse.Runner = None)`` + + - Reads the common parameters from ``info`` and sets the following instance variables: + + - ``self.mpicomm: Optional[MPI.Comm]`` : ``MPI.COMM_WORLD`` + + - ``self.mpisize: int`` : the number of MPI processes + + - ``self.mpirank: int`` : the rank of this process + + - When ``import mpi4py`` fails, ``self.mpicomm`` is set to ``None``, ``self.mpisize`` is set to 1, and ``self.mpirank`` is set to 0. + + - ``self.rng: np.random.Generator`` : pseudo random number generator + + - For details of the seed, see :ref:`the [algorithm] section of the input parameter ` + + - ``self.dimension: int`` : the dimension of the parameter space + + - ``self.label_list: List[str]`` : the name of each axes of the parameter space + + - ``self.root_dir: pathlib.Path`` : root directory + + - It is taken from ``info.base["root_dir"]``. + + - ``self.output_dir: pathlib.Path`` : output directory + + - It is taken from ``info.base["output_dir"]``. + + - ``self.proc_dir: pathlib.Path`` : working directory of each process + + - It is set to ``self.output_dir / str(self.mpirank)``. + - The directory will be made automatically. + - Each process performs an optimization algorithm in this directory. + + - ``self.timer: dict[str, dict]`` : dictionary storing elapsed time + + - Three empty dictinaries, ``"prepare"``, ``"run"``, and ``"post"``, will be defined. + + - ``self.checkpoint: bool`` : enable/disable checkpointing + + - ``self.checkpoint_steps`` + - ``self.checkpoint_interval`` + - ``self.checkpoint_file`` + + The parameters concerning the checkpointing feature are stored. + +- ``prepare(self) -> None`` + + - Prepares the algorithm. + - It should be called before ``self.run()`` is called. + +- ``run(self) -> None`` + + - Performs the algorithm + - The following steps are executed: + + #. Enter into the directory ``self.proc_dir``. + #. Run ``self.runner.prepare()``. + #. Run ``self._run()``. + #. Run ``self.runner.post()``. + #. Move to the original directory. + + - It should be called after ``self.prepare()`` is called. + +- ``post(self) -> Dict`` + + - Runs a post process of the algorithm, for example, writing the results into files. + - Enters into ``self.output_dir``, calls ``self._post()``, and returns to the original directory. + - It should be called after ``self.run()`` is called. + +- ``main(self, run_mode) -> Dict`` + + - Calls ``prepare``, ``run``, and ``post``. + - Measures the elapsed times for calling functions, and writes them into a file + - Takes an argument for the execution mode as a string. The default value is ``initialize``. + + - ``"initialize"``: start from the initial state. + - ``"resume"``: resume from the interrupted run. + - ``"continue"``: continue from the finished run. + + The argument contains ``"-resetrand"`` when the random number generator should be initialized. + The behavior of "continue" depends on the algorithm. + + - Returns the result of the optimization in the form of dictionary. + + +``Algorithm`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Algorithm`` provides a concrete description of the algorithm. +It is defined as a subclass of ``AlgorithmBase`` and should have the following methods. + +- ``__init__(self, info: odatse.Info, runner: odatse.Runner = None, domain = None)`` + + - The arguments ``info`` and ``runner`` should be transferred to the constructor of the base class: + + - ``super().__init__(info=info, runner=runner)`` + + - Reads ``info`` and sets information. + + - If ``domain`` is given, the search region should be taken from the ``domain`` parameter. + Otherwise, the search region should be created from ``info`` by ``odatse.domain.Region(info)`` (for continuous parameter space) or ``odatse.domain.MeshGrid(info)`` (for discrete parameter space). + +- ``_prepare(self) -> None`` + + - Describes pre-processes of the algorithm. + +- ``_run(self) -> None`` + + - Describes the algorithm body. + + - In order to obtain the value of the objective function ``f(x)`` for the search parameter ``x``, the method of Runner class should be called in the following manner: + + .. code-block:: python + + args = (step, set) + fx = self.runner.submit(x, args) + +- ``_post(self) -> Dict`` + + - Describes post-process of the algorithm. + + - Returns the result of the optimization in the form of dictionary. + + +Definition of ``Domain`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Two classes are preprared to specify the search region. + +``Region`` class +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Region`` is a helper class to define a continuous parameter space. + +- The constructor takes an ``Info`` object, or a dictionary in ``param=`` form. + + - When the ``Info`` object is given, the lower and upper bounds of the region, the units, and the initial values are obtained from ``Info.algorithm.param`` field. + + - When the dictionary is given, the corresponding data are taken from the dictionary data. + + - For details, see :ref:`[algorithm.param] subsection for minsearch ` + +- ``Initialize(self, rnd, limitation, num_walkers)`` should be called to set the initial values. + The arguments are the random number generator ``rng``, the constraint object ``limitation``, and the number of walkers ``num_walkers``. + +``MeshGrid`` class +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``MeshGrid`` is a helper class to define a discrete parameter space. + +- The constructor takes an ``Info`` object, or a dictionary in ``param=`` form. + + - When the ``Info`` object is given, the lower and upper bounds of the region, the units, and the initial values are obtained from ``Info.algorithm.param`` field. + + - When the dictionary is given, the corresponding data are taken from the dictionary data. + + - For details, see :ref:`[algorithm.param] subsection for mapper ` + +- ``do_split(self)`` should be called to divide the grid points and distribute them to MPI ranks. + +- For input and output, the following methods are provided. + + - A class method ``from_file(cls, path)`` is prepared that reads mesh data from ``path`` and creates an instance of ``MeshGrid`` class. + + - A method ``store_file(self, path)`` is prepared that writes the grid information to the file specified by ``path``. diff --git a/manual/v3.0.0/en/_sources/customize/common.rst.txt b/manual/v3.0.0/en/_sources/customize/common.rst.txt new file mode 100644 index 00000000..0ae92848 --- /dev/null +++ b/manual/v3.0.0/en/_sources/customize/common.rst.txt @@ -0,0 +1,123 @@ +Commons +================================ + +In this section, the components commonly used over the program are described. + + +``odatse.Info`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This class treats the input parameters. +It contains the following four instance variables. + +- ``base`` : ``dict[str, Any]`` + + - Parameters for whole program such as the directory where the output will be written. + +- ``solver`` : ``dict[str, Any]`` + + - Parameters for ``Solver`` + +- ``algorithm`` : ``dict[str, Any]`` + + - Parameters for ``Algorithm`` + +- ``runner`` : ``dict[str, Any]`` + + - Parameters for ``Runner`` + + +An instance of ``Info`` is initialized by passing a ``dict`` which has the following four sub dictionaries, ``base``, ``solver``, ``algorithm``, and ``runner``. (Some of them can be omitted.) +Each sub dictionary is set to the corresponding field of ``Info``. +Alternatively, it can be created by passing to the class method ``from_file`` a path to input file in TOML format. + + +``base`` items +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As items of ``base`` field, ``root_dir`` indicating the root dirctory of the calculation, and ``output_dir`` for output results will be set automatically as follows. + +- Root directory ``root_dir`` + + - The default value is ``"."`` (the current directory). + - The value of ``root_dir`` will be converted to an absolute path. + - The leading ``~`` will be expanded to the user's home directory. + - Specifically, the following code is executed: + + .. code-block:: python + + p = pathlib.Path(base.get("root_dir", ".")) + base["root_dir"] = p.expanduser().absolute() + +- Output directory ``output_dir`` + + - The leading ``~`` will be expanded to the user's home directory. + - If an absolute path is given, it is set as-is. + - If a relative path is given, it is regarded to be relative to ``root_dir``. + - The default value is ``"."``, that is, the same to ``root_dir`` + - Specifically, the following code is executed: + + .. code-block:: python + + p = pathlib.Path(base.get("work_dir", ".")) + p = p.expanduser() + base["work_dir"] = base["root_dir"] / p + + +``odatse.Runner`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Runner`` is a class that connects ``Algorithm`` and ``Solver``. +The constructor of ``Runner`` takes instances of ``Solver``, ``Info``, ``Mapping``, and ``Limitation``. +If the instance of ``Mapping`` is omitted, ``TrivialMapping`` is assumed that does no transformation. +If the instance of ``Limitation`` is omitted, ``Unlimited`` is assumed that do not impose constraints. + +``submit(self, x: np.ndarray, args: Tuple[int,int]) -> float`` method invokes the solver and returns the value of objective function ``f(x)``. +``submit`` internally uses the instance of ``Limitation`` to check whether the search parameter ``x`` satisfies the constraints. Then, it applies the instance of ``Mapping`` to obtain from ``x`` the input ``y = mapping(x)`` that is actually used by the solver. + +See :doc:`../input` for details how/which components of ``info`` ``Runner`` uses. + + +``odatse.Mapping`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Mapping`` is a class that describes mappings from the search parameters of the inverse problem analysis algorithms to the variables of the direct problem solvers. +It is defined as a function object class that has ``__call__(self, x: np.ndarray) -> np.ndarray`` method. +In the current version, a trivial transformation ``TrivialMapping`` and an affine mapping ``Affine`` are defined. + +``TrivialMapping`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``TrivialMapping`` provides a trivial transformation :math:`x\to x`, that is, no transformation. +It is taken as a default to the argument of Runner class. + +``Affine`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Affine`` provides an affine mapping :math:`x \to y = A x + b`. +The coefficients ``A`` and ``b`` should be given as constructor arguments, or passed as dictionary elements through the ``from_dict`` class method. +In case when they are specified in the input file of ODAT-SE, the format of the parameter may be referred to the input file section of the manual. + + +``odatse.Limitation`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Limitation`` is a class that describes constraints on the :math:`N` dimensional parameter space :math:`x` searched by the inverse problem analysis algorithms. +It is defined as a class that have the method ``judge(self, x: np.ndarray) -> bool``. +In the current version, ``Unlimited`` class that imposes no constraint, and ``Inequality`` class that represents the linear inequality constraint. + +``Unlimited`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Unlimited`` represents that no constraint is imposed. +``judge`` method always returns ``True``. +It is taken as a default to the argument of Runner class. + + +``Inequality`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Inequality`` is a class that expresses :math:`M` constraints imposed on :math:`N` dimensional search parameters :math:`x` in the form :math:`A x + b > 0` where :math:`A` is a :math:`M \times N` matrix and :math:`b` is a :math:`M` dimensional vector. + +The coefficients ``A`` and ``b`` should be given as constructor arguments, or passed as dictionary elements through the ``from_dict`` class method. +In case when they are specified in the input file of ODAT-SE, the format of the parameter may be referred to the input file section of the manual. diff --git a/manual/v3.0.0/en/_sources/customize/index.rst.txt b/manual/v3.0.0/en/_sources/customize/index.rst.txt new file mode 100644 index 00000000..2163441a --- /dev/null +++ b/manual/v3.0.0/en/_sources/customize/index.rst.txt @@ -0,0 +1,19 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +(For developers) User-defined algorithms and solvers +================================================================ + +ODAT-SE solves the inverse problems by the combination of ``Solver`` for the direct problems and ``Algorithm`` for the optimization methods. +Instead of using ``Solver`` and ``Algorithm`` provided by ODAT-SE, users can define and use their own components. +In this chapter, how to define ``Solver`` and ``Algorithm`` and to use them will be described. + +.. toctree:: + :maxdepth: 1 + + common + solver + algorithm + usage diff --git a/manual/v3.0.0/en/_sources/customize/solver.rst.txt b/manual/v3.0.0/en/_sources/customize/solver.rst.txt new file mode 100644 index 00000000..3b6fad24 --- /dev/null +++ b/manual/v3.0.0/en/_sources/customize/solver.rst.txt @@ -0,0 +1,69 @@ +``Solver`` +================================ + +``Solver`` is a class that describes the direct problem, providing a method ``evaluate`` that returns the value of the objective function from the input parameters. + +- ``Solver`` is define as a derived class of ``odatse.solver.SolverBase``. + + .. code-block:: python + + import odatse + + class Solver(odatse.solver.SolverBase): + pass + +- Constructor + + Solver class should have a constructor that takes an ``Info`` class object as an argument: + + .. code-block:: python + + def __init__(self, info: odatse.Info): + super().__init__(info) + + It is required to call the constructor of the base class with the info object. + There the following instance variables are introduced: + + - ``self.root_dir: pathlib.Path`` : Root directory + + This parameter is taken from ``info.base["root_dir"]``, and represents the directory in which ``odatse`` is executed. It can be referred as a root location when the external programs or data files are read. + + - ``self.output_dir: pathlib.Path`` : Output directory + + This parameter is taken from ``info.base["output_dir"]``, and used for the directory in which the result files are written. Usually, when the MPI parallelization is applied, the accumulated results are stored. + + - ``self.proc_dir: pathlib.Path`` : Working directory for each MPI process by the form ``self.output_dir / str(mpirank)`` + + The ``evaluate`` method of Solver is called from Runner with the ``proc_dir`` directory set as the current directory, in which the intermediate results produced by each rank are stored. When the MPI parallelization is not used, the rank number is treated as 0. + + The parameters for the Solver class can be obtained from ``solver`` field of ``info`` object. + The required parameters should be taken and stored. + +- ``evaluate`` method + + The form of ``evaluate`` method should be as follows: + + .. code-block:: python + + def evaluate(self, x, args=(), nprocs=1, nthreads=1) -> float: + pass + + This method evaluates the objective function at a given parameter value `x` and returns the result. It takes the following arguments: + + - ``x: np.ndarray`` + + The parameter value in :math:`N` dimensional vector of numpy.ndarray type. + + - ``args: Tuple = ()`` + + The additional arguments passed from the Algorithm in the form of a Tuple of two integers. + One is the step count that corresponds to the Monte Carlo steps for MC type algorithms, or the index of the grid point for grid search algorithm. + The other is the set number that represents :math:`n`-th iteration. + + - ``nprocs: int = 1`` + + - ``nthreads: int = 1`` + + The number of processes and threads that specify how to run the solver in MPI/thread parallelisation. In the current version, ``nprocs=1`` and ``nthreads=1`` are accepted. + + The ``evaluate`` method returns the value of the objective function as a float number. diff --git a/manual/v3.0.0/en/_sources/customize/usage.rst.txt b/manual/v3.0.0/en/_sources/customize/usage.rst.txt new file mode 100644 index 00000000..5e0bc714 --- /dev/null +++ b/manual/v3.0.0/en/_sources/customize/usage.rst.txt @@ -0,0 +1,48 @@ +Usage +================================ + +The following flow solves the optimization problem. +The number of flow corresponds the comment in the program example. + +1. Define your ``Algorithm`` and/or ``Solver``. + + - Classes that ODAT-SE provides are available, of course. + +2. Prepare the input parameter, ``info: odatse.Info``. + + - ``Info`` class has a class method to read input files in TOML format. + It is also possible to prepare a set of parameters as a dict and to pass it to the constructor of ``Info`` class. + +3. Instantiate ``solver: Solver``, ``runner: odatse.Runner``, and ``algorithm: Algorithm``. + +4. Invoke ``algorithm.main()``. + + +Example: + +.. code-block:: python + + import sys + import odatse + + # (1) + class Solver(odatse.solver.SolverBase): + # Define your solver + ... + + class Algorithm(odatse.algorithm.AlgorithmBase): + # Define your algorithm + ... + + + # (2) + input_file = sys.argv[1] + info = odatse.Info.from_file(input_file) + + # (3) + solver = Solver(info) + runner = odatse.Runner(solver, info) + algorithm = Algorithm(info, runner) + + # (4) + result = algorithm.main() diff --git a/manual/v3.0.0/en/_sources/index.rst.txt b/manual/v3.0.0/en/_sources/index.rst.txt new file mode 100644 index 00000000..db7379c1 --- /dev/null +++ b/manual/v3.0.0/en/_sources/index.rst.txt @@ -0,0 +1,23 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to ODAT-SE documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + start + tutorial/index + input + output + algorithm/index + solver/index + tool + customize/index + acknowledgement + contact diff --git a/manual/v3.0.0/en/_sources/input.rst.txt b/manual/v3.0.0/en/_sources/input.rst.txt new file mode 100644 index 00000000..7058d66f --- /dev/null +++ b/manual/v3.0.0/en/_sources/input.rst.txt @@ -0,0 +1,278 @@ +Input file +================================ + +As the input file format, `TOML `_ format is used. +The input file consists of the following four sections. + +- ``base`` + + - Specify the basic parameters about ODAT-SE. + +- ``solver`` + + - Specify the parameters about ``Solver`` . + +- ``algorithm`` + + - Specify the parameters about ``Algorithm`` . + +- ``runner`` + + - Specify the parameters about ``Runner`` . + + +[``base``] section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``dimension`` + + Format: Integer + + Description: Dimension of the search space (number of parameters to search) + +- ``root_dir`` + + Format: string (default: The directory where the program was executed) + + Description: Name of the root directory. The origin of the relative paths to input files. + +- ``output_dir`` + + Format: string (default: The directory where the program was executed) + + Description: Name of the directory to output the results. + +[``solver``] section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``name`` determines the type of solver. Each parameter is defined for each solver. + +- ``name`` + + Format: String + + Description: Name of the solver. The following solvers are available. + + - ``analytical`` : Solver to provide analytical solutions (mainly used for testing). + + - ``sim-trhepd-rheed`` : + Solver to calculate Total-reflection high energy positron diffraction (TRHEPD) or Reflection High Energy Electron Diffraction (RHEED) intensities. + + - ``sxrd`` : Solver for Surface X-ray Diffraction (SXRD) + + - ``leed`` : Solver for Low-energy Electron Diffraction (LEED) + +- ``dimension`` + + Format: Integer (default: ``base.dimension``) + + Description: + Number of input parameters for Solvers + +See :doc:`solver/index` for details of the various solvers and their input/output files. + +.. _input_parameter_algorithm: + +[``algorithm``] section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``name`` determines the type of algorithm. Each parameter is defined for each algorithm. + +- ``name`` + + Format: String + + Description: Algorithm name. The following algorithms are available. + + - ``minsearch`` : Minimum value search using Nelder-Mead method + + - ``mapper`` : Grid search + + - ``exchange`` : Replica Exchange Monte Carlo method + + - ``pamc`` : Population Annealing Monte Carlo method + + - ``bayes`` : Bayesian optimization + +- ``seed`` + + Format: Integer + + Description: + A parameter to specify seeds of the pseudo-random number generator used for random generation of initial values, Monte Carlo updates, etc. + For each MPI process, the value of ``seed + mpi_rank * seed_delta`` is given as seeds. + If omitted, the initialization is done by `the Numpy's prescribed method `_. + +- ``seed_delta`` + + Format: Integer (default: 314159) + + Description: + A parameter to calculate the seed of the pseudo-random number generator for each MPI process. + For details, see the description of ``seed``. + +- ``checkpoint`` + + Format: Boolean (default: false) + + Description: + A parameter to specify whether the intermediate states are periodically stored to files. The final state is also saved. In case when the execution is terminated, it will be resumed from the latest checkpoint. + +- ``checkpoint_steps`` + + Format: Integer (default: 16,777,216) + + Description: + A parameter to specify the iteration steps between the previous and next checkpoints. One iteration step corresponds to one evaluation of grid point in the mapper algorithm, one evaluation of Bayesian search in the bayes algorithm, and one local update in the Monte Carlo (exchange and PAMC) algorithms. + The default value is a sufficiently large number of steps. To enable checkpointing, at least either of ``checkpoint_steps`` or ``checkpoint_interval`` should be specified. + +- ``checkpoint_interval`` + + Format: Floating point number (default: 31,104,000) + + Description: + A parameter to specify the execution time between the previous and next checkpoints in unit of seconds. + The default value is a sufficiently long period (360 days). To enable checkpointing, at least either of ``checkpoint_steps`` or ``checkpoint_interval`` should be specified. + +- ``checkpoint_file`` + + Format: String (default: ``"status.pickle"``) + + Description: + A parameter to specify the name of output file to which the intermediate state is written. + The files are generated in the output directory of each process. + The past three generations are kept with the suffixes .1, .2, and .3 . + + +See :doc:`algorithm/index` for details of the various algorithms and their input/output files. + +[``runner``] section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section sets the configuration of ``Runner``, which bridges ``Algorithm`` and ``Solver``. +It has three subsections, ``mapping``, ``limitation``, and ``log`` . + +[``runner.mapping``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section defines the mapping from an :math:`N` dimensional parameter searched by ``Algorithm``, :math:`x`, to an :math:`M` dimensional parameter used in ``Solver``, :math:`y` . +In the case of :math:`N \ne M`, the parameter ``dimension`` in ``[solver]`` section should be specified. + +In the current version, the affine mapping (linear mapping + translation) :math:`y = Ax+b` is available. + +- ``A`` + + Format: List of list of float, or a string (default: ``[]``) + + Description: + :math:`N \times M` matrix :math:`A`. An empty list ``[]`` is a shorthand of an identity matrix. + If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example). + + +- ``b`` + + Format: List of float, or a string (default: ``[]``) + + Description: + :math:`M` dimensional vector :math:`b`. An empty list ``[]`` is a shorthand of a zero vector. + If you want to set it by a string, arrange the elements of the vector separated with spaces. + +For example, both :: + + A = [[1,1], [0,1]] + +and :: + + A = """ + 1 1 + 0 1 + """ + +mean + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right). + + +[``limitation``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section defines the limitation (constraint) in an :math:`N` dimensional parameter searched by ``Algorithm``, :math:`x`, in addition of ``min_list`` and ``max_list``. + +In the current version, a linear inequation with the form :math:`Ax+b>0` is available. + +- ``co_a`` + + Format: List of list of float, or a string (default: ``[]``) + + Description: + :math:`N \times M` matrix :math:`A`. An empty list ``[]`` is a shorthand of an identity matrix. + If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example). + +- ``co_b`` + + Format: List of float, or a string (default: ``[]``) + + Description: + :math:`M` dimensional vector :math:`b`. An empty list ``[]`` is a shorthand of a zero vector. + If you want to set it by a string, arrange the elements of the vector separated with spaces. + +For example, both :: + + A = [[1,1], [0,1]] + +and :: + + A = """ + 1 1 + 0 1 + """ + +mean + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right). + + +[``log``] section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Setting parametrs related to logging of solver calls. + +- ``filename`` + + Format: String (default: "runner.log") + + Description: Name of log file. + +- ``interval`` + + Format: Integer (default: 0) + + Description: + The log will be written out every time solver is called ``interval`` times. + If the value is less than or equal to 0, no log will be written. + +- ``write_result`` + + Format: Boolean (default: false) + + Description: Whether to record the output from solver. + +- ``write_input`` + + Format: Boolean (default: false) + + Description: Whether to record the input to solver. diff --git a/manual/v3.0.0/en/_sources/introduction.rst.txt b/manual/v3.0.0/en/_sources/introduction.rst.txt new file mode 100644 index 00000000..5b059a60 --- /dev/null +++ b/manual/v3.0.0/en/_sources/introduction.rst.txt @@ -0,0 +1,102 @@ +Introduction +================================ + +What is ODAT-SE ? +-------------------------------- + +Open Data Analysis Tool for Science and Engineering (ODAT-SE) is a framework for applying a search algorithm to a direct problem solver to find the optimal solution. +It has been developed by the name 2DMAT, and since version 3, it is organized as an open platform for data analysis by modularizing direct problem solvers and search algorithms. + +As the standard direct problem solver, the experimental data analysis software for two-dimensional material structure analysis is prepared. The direct problem solver gives the deviation between the experimental data and the calculated data obtained under the given parameters such as atomic positions as a loss function used in the inverse problem. The optimal parameters are estimated by minimizing the loss function using a search algorithm. For further use, the original direct problem solver or the search algorithm can be defined by users. +In the current version, for solving a direct problem, ODAT-SE offers the wrapper of the solver for the total-reflection high-energy positron diffraction (TRHEPD) experiment[1, 2], sxrd[3], and leed[4]. +As algorithms, it offers the Nelder-Mead method[5], the grid search method[6], the Bayesian optimization method[7], the replica exchange Monte Carlo method[8], and the population annealing Monte Carlo method[9-11]. + +In the future, we plan to add other direct problem solvers and search algorithms in ODAT-SE. + + +[1] As a review, see `Y. Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019) `_. + +[2] `T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022). `_ + +[3] `W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252, 5259 (2006). `_ + +[4] `M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). `_ + +[5] `K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020) `_. + +[6] `K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series, 9, 011301 (2023) `_. + +[7] `Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022) `_ + +[8] `K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996) `_, `R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986) `_. + +[9] `R. M. Neal, Statistics and Computing 11, 125-139 (2001). `_ + +[10] `K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003). `_ + +[11] `J. Machta, Phys. Rev. E 82, 026704 (2010). `_ + +License +-------------------------------- +| This package is distributed under `Mozilla Public License version 2.0 (MPL-2.0) `_. + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +This software was developed with the support of "Project for advancement of software usability in materials science" of The Institute for Solid State Physics, The University of Tokyo. +We hope that you cite the following reference when you publish the results using 2DMAT / ODAT-SE: + +`"Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures", Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, Computer Physics Communications 280, 108465 (2022) `_. + +BibTeX:: + + @article{MOTOYAMA2022108465, + title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures}, + journal = {Computer Physics Communications}, + volume = {280}, + pages = {108465}, + year = {2022}, + issn = {0010-4655}, + doi = {https://doi.org/10.1016/j.cpc.2022.108465}, + url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849}, + author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi} + } + +Version Information +-------------------------------- + +- ODAT-SE + + - v3.0.0: 2024-11-25 + +- 2DMAT + + - v2.1.0: 2022-04-08 + - v2.0.0: 2022-01-17 + - v1.0.1: 2021-04-15 + - v1.0.0: 2021-03-12 + - v0.1.0: 2021-02-08 + + +Main developers +-------------------------------- +ODAT-SE has been developed by following members. + +- ODAT-SE v3.0.0 - + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - T. Aoyama (The Institute for Solid State Physics, The University of Tokyo) + - T. Hoshi (National Institute for Fusion Science) + +- 2DMAT v2.0.0 - + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - H. Iwamoto (Department of Applied Mathematics and Physics, Tottori University) + - T. Hoshi (Department of Applied Mathematics and Physics, Tottori University) + +- 2DMAT v0.1.0 - v1.0.1 + + - Y. Motoyama (The Institute for Solid State Physics, The University of Tokyo) + - K. Yoshimi (The Institute for Solid State Physics, The University of Tokyo) + - T. Hoshi (Department of Applied Mathematics and Physics, Tottori University) diff --git a/manual/v3.0.0/en/_sources/output.rst.txt b/manual/v3.0.0/en/_sources/output.rst.txt new file mode 100644 index 00000000..b9ec3097 --- /dev/null +++ b/manual/v3.0.0/en/_sources/output.rst.txt @@ -0,0 +1,59 @@ +Output files +===================== + +See :doc:`solver/index` and :doc:`algorithm/index` for the output files of each ``Solver`` and ``Algorithm``. + +Common file +~~~~~~~~~~~~~~~~~~ + +``time.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The total time taken for the calculation for each MPI rank is outputted. +These files will be output under the subfolders of each rank respectively. +The time taken to pre-process the calculation, the time taken to compute, and the time taken to post-process the calculation are listed in the ``prepare`` , ``run`` , and ``post`` sections. + +The following is an example of the output. + +.. code-block:: + + #prepare + total = 0.007259890999989693 + #run + total = 1.3493346729999303 + - file_CM = 0.0009563499997966574 + - submit = 1.3224223930001244 + #post + total = 0.000595873999941432 + + +``runner.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The log information about solver calls for each MPI rank is outputted. +These files will be output under the subfolder of each rank. +The output is only available when the ``runner.log.interval`` parameter is a positive integer in the input. + +- The first column is the serial number of the solver call. +- The second column is the time elapsed since the last solver call. +- The third column is the time elapsed since the start of the calculation. + +The following is an example of the output. + +.. code-block:: + + # $1: num_calls + # $2: elapsed_time_from_last_call + # $3: elapsed_time_from_start + + 1 0.0010826379999999691 0.0010826379999999691 + 2 6.96760000000185e-05 0.0011523139999999876 + 3 9.67080000000009e-05 0.0012490219999999885 + 4 0.00011765699999999324 0.0013666789999999818 + 5 4.965899999997969e-05 0.0014163379999999615 + 6 8.666900000003919e-05 0.0015030070000000006 + ... + +``status.pickle`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If ``algorithm.checkpoint`` is set to true, the intermediate states are stored to ``status.pickle`` (or the filename specified by the ``algorithm.checkpoint_file`` parameter) for each MPI process in its subfolder. +They are read when the execution is resumed. +The content of the file depends on the algorithm. diff --git a/manual/v3.0.0/en/_sources/solver/analytical.rst.txt b/manual/v3.0.0/en/_sources/solver/analytical.rst.txt new file mode 100644 index 00000000..1ab84fdc --- /dev/null +++ b/manual/v3.0.0/en/_sources/solver/analytical.rst.txt @@ -0,0 +1,55 @@ +``analytical`` solver +************************ + +``analytical`` is a ``Solver`` that computes a predefined benchmark function :math:`f(x)` for evaluating the performance of search algorithms. + +Input parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``funtion_name`` parameter in the ``solver`` section specifies the function to use. + +- ``function_name`` + + Format: string + + Description: Function name. The following functions are available. + + - ``quadratics`` + + - Quadratic function + + .. math:: + + f(\vec{x}) = \sum_{i=1}^N x_i^2 + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + + - ``rosenbrock`` + + - `Rosenbrock function `_ + + .. math:: + + f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right] + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)` + + - ``ackley`` + + - `Ackley function `_ + + .. math:: + + f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right] + + - The optimized value :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + + - ``himmerblau`` + + - `Himmerblau function `_ + + .. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + + - The optimized value :math:`f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0` diff --git a/manual/v3.0.0/en/_sources/solver/index.rst.txt b/manual/v3.0.0/en/_sources/solver/index.rst.txt new file mode 100644 index 00000000..61fb26ea --- /dev/null +++ b/manual/v3.0.0/en/_sources/solver/index.rst.txt @@ -0,0 +1,19 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Direct Problem Solver +====================== + +Direct problem solver ``Solver`` calculates the function to be optimized :math:`f(x)` at the search parameter :math:`x`. + +.. toctree:: + :maxdepth: 1 + + analytical + +.. + sim-trhepd-rheed + sxrd + leed diff --git a/manual/v3.0.0/en/_sources/start.rst.txt b/manual/v3.0.0/en/_sources/start.rst.txt new file mode 100644 index 00000000..bf7889a0 --- /dev/null +++ b/manual/v3.0.0/en/_sources/start.rst.txt @@ -0,0 +1,83 @@ +Installation of ODAT-SE +================================ + +Prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- Python3 (>=3.9) + + - The following Python packages are required. + - tomli >= 1.2 + - numpy >= 1.14 + + - Optional packages + + - mpi4py (required for grid search) + - scipy (required for Nelder-Mead method) + - physbo (>=2.0, required for Baysian optimization) + + +How to download and install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can install the ODAT-SE python package and the ``odatse`` command following the instructions shown below. + +- Installation using PyPI (recommended) + + - ``python3 -m pip install ODAT-SE`` + + - ``--user`` option to install locally (``$HOME/.local``) + + - If you use ``ODAT-SE[all]``, optional packages will be installed at the same time. + +- Installation from source code + + #. ``git clone https://github.com/issp-center-dev/ODAT-SE`` + #. ``python3 -m pip install ./ODAT-SE`` + + - The ``pip`` version must be 19 or higher (can be updated with ``python3 -m pip install -U pip``). + +- Download the sample files + + - Sample files are included in the source code. + - ``git clone https://github.com/issp-center-dev/ODAT-SE`` + + +How to run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ODAT-SE, the analysis is carried out by using a predefined optimization algorithm ``Algorithm`` and a direct problem solver ``Solver``. + +.. code-block:: bash + + $ odatse input.toml + +See :doc:`algorithm/index` for the predefined ``Algorithm`` and :doc:`solver/index` for the ``Solver``. + +The direct problem solvers for analyses of experimental data of two-dimensional material structure are provided as separate modules. +To perform these analyses, you need to install the modules and the required software packages. +At present, the following modules are provided: + +- odatse-STR module for Total Refrection High-energy Positron Diffraction (TRHEPD) + +- odatse-SXRD module for Surface X-ray Diffraction (SXRD) + +- odatse-LEED module for Low-energy Electron Diffraction (LEED) + +If you want to prepare the ``Algorithm`` or ``Solver`` by yourself, use the ODAT-SE package. +See :doc:`customize/index` for details. + +The program can be executed without installing ``odatse`` command; instead, run ``src/odatse_main.py`` script directly as follows. It would be convenient when you are rewriting programs. + +.. code-block:: bash + + $ python3 src/odatse_main.py input + + +How to uninstall +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please type the following command: + +.. code-block:: bash + + $ python3 -m pip uninstall ODAT-SE diff --git a/manual/v3.0.0/en/_sources/tool.rst.txt b/manual/v3.0.0/en/_sources/tool.rst.txt new file mode 100644 index 00000000..0dac1dfb --- /dev/null +++ b/manual/v3.0.0/en/_sources/tool.rst.txt @@ -0,0 +1,64 @@ +Related Tools +================================ + +``odatse_neighborlist`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This tool generates a neighborhood-list file from the mesh file. + +When you install ODAT-SE via ``pip`` command, ``odatse_neighborlist`` is also installed under the ``bin``. +A python script ``src/odatse_neighborlist.py`` is also available. + +Usage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pass a path to the mesh file as an argument. +The filename of the generated neighborhood-list file is specified by ``-o`` option. + +.. code-block:: bash + + $ odatse_neighborlist -o neighborlist.txt MeshData.txt + + Or + + $ python3 src/odatse_neighborlist.py -o MeshData.txt + + +The following command-line options are available. + +- ``-o output`` or ``--output output`` + + - The filename of output (default: ``neighborlist.txt``) + +- ``-u "unit1 unit2..."`` or ``--unit "unit1 unit2..."`` + + - Length scale for each dimension of coordinate (default: 1.0 for all dims) + + - Put values splitted by whitespaces and quote the whole + + - e.g.) ``-u "1.0 0.5"`` + + - Each dimension of coordinate is divided by the corresponding ``unit``. + +- ``-r radius`` or ``--radius radius`` + + - A pair of nodes where the Euclidean distance is less than ``radius`` is considered a neighborhood (default: 1.0) + - Distances are calculated in the space after coordinates are divided by ``-u`` + +- ``-q`` or ``--quiet`` + + - Do not show a progress bar + - Showing a progress bar requires ``tqdm`` python package + +- ``--allow-selfloop`` + + - Include :math:`i` in the neighborhoods of :math:`i` itself + +- ``--check-allpairs`` + + - Calculate distances of all pairs + - This is for debug + + +MPI parallelization is available. + diff --git a/manual/v3.0.0/en/_sources/tutorial/bayes.rst.txt b/manual/v3.0.0/en/_sources/tutorial/bayes.rst.txt new file mode 100644 index 00000000..a0930468 --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/bayes.rst.txt @@ -0,0 +1,163 @@ +Optimization by Bayesian Optimization +======================================== + +This tutorial describes how to estimate the minimization problem of Himmelblau function by using Bayesian optimization (BO). +ODAT-SE uses `PHYSBO `_ for BO. +PHYSBO package should be installed beforehand. + +Sample files +~~~~~~~~~~~~~~~~~~~~~~~~ + +Sample files are available from ``sample/analytical/bayes`` . +This directory includes the following files: + +- ``input.toml`` + + The input file of odatse + +- ``do.sh`` + + Script files for running this tutorial + +In addition, ``plot_himmel.py`` in ``sample`` directory is used to visualize the result. + + +Input files +~~~~~~~~~~~~~~~~~~~ + +This subsection describes the input file. +For details, see :ref:`the manual of bayes `. + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [algorithm] + name = "bayes" + seed = 12345 + + [algorithm.param] + min_list = [-6.0, -6.0] + max_list = [ 6.0, 6.0] + num_list = [61, 61] + + [algorithm.bayes] + random_max_num_probes = 20 + bayes_max_num_probes = 40 + + +The contents of ``[base]``, ``[solver]``, and ``[runner]`` sections are the same as those for the search by the Nelder-Mead method (``minsearch``). + +``[algorithm]`` section specifies the algorithm to use and its settings. + +- ``name`` is the name of the algorithm you want to use, and in this tutorial we will do a Bayesian optimization analysis, so specify ``bayes``. + +- ``seed`` specifies the initial input of random number generator. + +``[algorithm.param]`` section specifies the range of parameters to search and their initial values. + +- ``min_list`` and ``max_list`` specify the minimum and maximum values of the search grid, respectively. + +- ``num_list`` specifies the number of grid points along each parameter. + +``[algorithm.bayes]`` section sets the parameters for Bayesian optimization. + +- ``random_max_num_probes`` specifies the number of random searches before Bayesian optimization. + +- ``bayes_max_num_probes`` specifies the number of Bayesian searches. + +For details on other parameters that can be specified in the input file, see the chapter on input files of ``bayes``. + + +Calculation +~~~~~~~~~~~~ + +First, move to the folder where the sample file is located. (Hereinafter, it is assumed that you are the root directory of ODAT-SE.) + +.. code-block:: + + $ cd sample/analytical/bayes + +Then, run the main program. It will take a few secondes on a normal PC. + +.. code-block:: + + $ python3 ../../../src/odatse_main.py input.toml | tee log.txt + +By executing the program, a directory with the name ``0`` is created under ``output`` directory, and the results are written in it. +The following standard output will be shown: + +.. code-block:: + + # parameter + random_max_num_probes = 10 + bayes_max_num_probes = 20 + score = TS + interval = 5 + num_rand_basis = 5000 + value_01 = 5.10000 + value_02 = 4.90000 + R-factor = 0.037237314010261195 + 0001-th step: f(x) = -0.037237 (action=150) + current best f(x) = -0.037237 (best action=150) + + value_01 = 4.30000 + value_02 = 3.50000 + ... + +A list of hyperparameters, followed by candidate parameters at each step and the corresponding function values are shown first. +It also outputs the grid index (``action``) and ``f(x)`` of the best value at that time. +The final estimated parameters are output to ``output/BayesData.txt``. + +In this case, ``BayesData.txt`` can be seen as the following + +.. code-block:: + + #step x1 x2 fx x1_action x2_action fx_action + 0 -2.4 -0.7999999999999998 113.2192 -2.4 -0.7999999999999998 113.2192 + 1 -2.4 -0.7999999999999998 113.2192 1.6000000000000005 4.600000000000001 263.12320000000045 + 2 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.8000000000000007 -0.39999999999999947 28.995199999999958 + 3 2.8000000000000007 -0.39999999999999947 28.995199999999958 4.800000000000001 5.800000000000001 1306.739200000001 + 4 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.3999999999999995 2.5999999999999996 44.16320000000003 + 5 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.200000000000001 -5.2 623.6672 + + 6 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.1999999999999993 2.200000000000001 65.45919999999997 + 7 4.200000000000001 -1.7999999999999998 23.619200000000067 4.200000000000001 -1.7999999999999998 23.619200000000067 + 8 4.200000000000001 -1.7999999999999998 23.619200000000067 -2.5999999999999996 -0.1999999999999993 111.10720000000002 + 9 4.200000000000001 -1.7999999999999998 23.619200000000067 0.6000000000000005 0.8000000000000007 130.00319999999994 + 10 4.200000000000001 -1.7999999999999998 23.619200000000067 -0.5999999999999996 -0.5999999999999996 178.7552 + ... + 38 3.200000000000001 1.8000000000000007 1.3952000000000133 3.200000000000001 -1.3999999999999995 8.051199999999973 + 39 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.8 -3.0 3.433599999999999 + 40 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.0 -2.8 27.705600000000004 + 41 3.6000000000000014 -1.7999999999999998 0.051200000000003215 3.6000000000000014 -1.7999999999999998 0.051200000000003215 + 42 3.6000000000000014 -1.7999999999999998 0.051200000000003215 2.0 2.5999999999999996 22.457599999999996 + ... + + +The first column contains the number of steps, and the second, third, and fourth columns contain ``x2``, ``x2``, and ``f(x)``, which give the highest score at that time. +This is followed by the candidate ``x1``, ``x2`` and ``f(x)`` for that step. +In this case, you can see that the correct solution is obtained at the 41st step. + + +Visualization +~~~~~~~~~~~~~~~~~~~ + +You can see at what step the parameter gave the minimum score by looking at ``BayesData.txt``. + +.. code-block:: + + $ python3 ../plot_himmel.py --xcol=1 --ycol=2 --format="-o" --output=output/res.pdf output/BayesData.txt + $ python3 ../plot_himmel.py --xcol=4 --ycol=5 --format="o" --output=output/actions.pdf output/BayesData.txt + +By executing the above commands, ``output/actions.pdf`` and ``output/res.pdf`` will be created that plots the grid points evaluated during the Bayes optimization process, and the sequence of the points that yield the least scores, respectively, on top of the contour of Himmelblau function. + +.. figure:: ../../../common/img/res_bayes_plot.* + + The grid points evaluated during the Bayesian optimization (left) and the history of points that yield the least scores (right). diff --git a/manual/v3.0.0/en/_sources/tutorial/exchange.rst.txt b/manual/v3.0.0/en/_sources/tutorial/exchange.rst.txt new file mode 100644 index 00000000..053577a8 --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/exchange.rst.txt @@ -0,0 +1,168 @@ +Optimization by replica exchange Monte Carlo +================================================ + +This tutorial describes how to estimate the minimization problem of Himmelblau function by using the replica exchange Monte Carlo method (RXMC). + +Sample files +~~~~~~~~~~~~~~~~~~ + +Sample files are available from ``sample/analytical/exchange`` . +This directory includes the following files: + +- ``input.toml`` + + The input file of odatse + +- ``do.sh`` + + Script files for running this tutorial + + +Input files +~~~~~~~~~~~~~ + +This subsection describes the input file. +For details, see the input file section of the manual. + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [algorithm] + name = "exchange" + seed = 12345 + + [algorithm.param] + min_list = [3.0, 3.0] + max_list = [6.0, 6.0] + step_list = [0.3, 0.3] + + [algorithm.exchange] + Tmin = 0.01 + Tmax = 100.0 + numsteps = 10000 + numsteps_exchange = 100 + nreplica_per_proc = 20 + + +In the following, we will briefly describe this input file. +For details, see the manual of :doc:`../algorithm/exchange`. + +The contents of ``[base]``, ``[solver]``, and ``[runner]`` sections are the same as those for the search by the Nelder-Mead method (``minsearch``). + +``[algorithm]`` section specifies the algorithm to use and its settings. + +- ``name`` is the name of the algorithm you want to use. In this tutorial we will use RXMC, so specify ``exchange``. + +- ``seed`` is the seed that a pseudo-random number generator uses. + +``[algorithm.param]`` section sets the parameter space to be explored. + +- ``min_list`` is a lower bound and ``max_list`` is an upper bound. + +- ``unit_list`` is step length in one Monte Carlo update (deviation of Gaussian distribution). + +``[algorithm.exchange]`` section sets the hyper parameters for RXMC. + +- ``numstep`` is the number of Monte Carlo steps. + +- ``numsteps_exchange`` is the number of steps between temperature exchanges. + +- ``Tmin``, ``Tmax`` are the minimum and the maximum of temperature, respectively. + +- When ``Tlogspace`` is ``true``, the temperature points are distributed uniformly in the logarithmic space. + +- ``nreplica_per_proc`` specifies the number of replicas that one MPI process handles. + + +Calculation +~~~~~~~~~~~~ + +First, move to the folder where the sample file is located. (Hereinafter, it is assumed that you are the root directory of ODAT-SE.) + +.. code-block:: + + $ cd sample/analytical/exchange + +Then, run the main program. It will take a few secondes on a normal PC. + +.. code-block:: + + $ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt + + +Here, the calculation is performed using MPI parallel with 4 processes. +If you are using Open MPI and you request more processes than the number of cores, you need to add the ``--oversubscribe`` option to the ``mpiexec`` command. + +When executed, a folder for each MPI rank will be created under ``output`` directory, and a ``trial.txt`` file containing the parameters evaluated in each Monte Carlo step and the value of the objective function, and a ``result.txt`` file containing the parameters actually adopted will be created. + +These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters. + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 0.01 170.0 0.0 0.0 + 0 1 0.01123654800138751 187.94429125133564 5.155393113805774 -2.203493345018569 + 0 2 0.012626001098748564 3.179380982615041 -3.7929742598748666 -3.5452766573635235 + 0 3 0.014187266741165962 108.25464277273859 0.8127003489802398 1.1465364357510186 + 0 4 0.01594159037455999 483.84183395038843 5.57417423682746 1.8381251624588506 + 0 5 0.01791284454622004 0.43633134370869153 2.9868796504069426 1.8428384502208246 + 0 6 0.020127853758499396 719.7992581349758 2.972577711255287 5.535680832873856 + 0 7 0.022616759492228647 452.4691017123836 -5.899340424701358 -4.722667479627368 + 0 8 0.025413430367026365 45.5355817998709 -2.4155554347674215 1.8769341969872393 + 0 9 0.028555923019901074 330.7972369561986 3.717750630491217 4.466110964691396 + 0 10 0.032086999973704504 552.0479484091458 5.575771168463163 2.684224163039442 + ... + +``best_result.txt`` is filled with information about the parameter with the optimal objective function, the rank from which it was obtained, and the Monte Carlo step. + +.. code-block:: + + nprocs = 80 + rank = 3 + step = 8025 + walker = 17 + fx = 3.358076734724385e-06 + x1 = 2.9998063442504126 + x2 = 1.999754886043102 + + +In ODAT-SE, one replica holds samples at different temperatures because of the temperature exchanges. The ``result.txt`` in each rank folder records the data sampled by each replica. +The data reorganized for each temperature point is written to ``output/result_T%.txt``, where ``%`` is the index of the temperature point. +The first column is the step, the second column is the rank, the third column is the value of the objective function, and the fourth and subsequent columns are the parameters. +Example: + +.. code-block:: + + # T = 0.014187266741165962 + 0 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 1 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 2 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 3 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 4 3 93.5034551820852 1.3377081691728905 0.8736706475438123 + 5 3 81.40963740872147 1.4541906604820898 1.0420053981467825 + ... + + +Visualization +~~~~~~~~~~~~~~~~~~~ + +By plotting ``output/result_T%.txt``, you can estimate regions where the parameters with small function values are located. +By executing the following command, the figures of two-dimensional plot ``res_T%.png`` will be generated. + +.. code-block:: + + $ python3 ../plot_himmel.py --xcol=3 --ycol=4 --skip=20 --format="o" --output=output/res_T0.png output/result_T0.txt + +Looking at the resulting diagram, we can see that the samples are concentrated near the minima of ``f(x)``. By changing the index of the temperature, the sampling points scatters over the region at high temperature, while they tend to concentrate on the minima at low temperature. + +.. figure:: ../../../common/img/res_exchange.* + + Distribution of sampling points on two-dimensional parameter space at :math:`T=\{35.02, 3.40, 0.33, 0.01\}`. + diff --git a/manual/v3.0.0/en/_sources/tutorial/index.rst.txt b/manual/v3.0.0/en/_sources/tutorial/index.rst.txt new file mode 100644 index 00000000..b69e0dd1 --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/index.rst.txt @@ -0,0 +1,45 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Tutorials +================================== + +In these tutorials, how to perform inverse problem analyses using ODAT-SE is explained by examples taken from minimization of analytical functions. +In ODAT-SE, the algorithms for solving the inverse problem can be selected from the following algorithms: + +- ``minsearch`` + + Nealder-Mead method. + +- ``mapper_mpi`` + + Entire search over a grid for a given parameter. + +- ``bayes`` + + Bayesian optimization. + +- ``exchange`` + + Sampling by the replica exchange Monte Carlo method. + +- ``pamc`` + + Sampling by the population annealing Monte Carlo method. + +In the following sections, the procedures to run these algorithms are provided. +In addition, the usage of ``[runner.limitation]`` to apply limitations to the search region will be described. In the end of the section, how to define a direct problem solver wil be explained by a simple example. + +.. toctree:: + :maxdepth: 1 + + intro + minsearch + mapper + bayes + exchange + pamc + limitation + solver_simple diff --git a/manual/v3.0.0/en/_sources/tutorial/intro.rst.txt b/manual/v3.0.0/en/_sources/tutorial/intro.rst.txt new file mode 100644 index 00000000..2e0f70c1 --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/intro.rst.txt @@ -0,0 +1,18 @@ +Minimization of an analytical function +================================================================ + +As an example of direct problem solver, the minimization of Himmelblau function among the Analytical solver included in ODAT-SE will be discussed in these tutorials. +The Himmelblau function is a two-variable function given as follows, having multiple number of minima. It is used as a benchmark for the evaluation of optimization algorithms. + +.. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + +The minimum value :math:`f(x,y)=0` is given at :math:`(x,y)` that equals to :math:`(3.0, 2.0)`, :math:`(-2.805118, 3.131312)`, :math:`(-3.779310, -3.283186)`, and :math:`(3.584428, -1.848126)`. + +.. figure:: ../../../common/img/plot_himmelblau.* + + The plot of Himmelblau function. + + +[1] D. Himmelblau, Applied Nonlinear Programming, McGraw-Hill, 1972. diff --git a/manual/v3.0.0/en/_sources/tutorial/limitation.rst.txt b/manual/v3.0.0/en/_sources/tutorial/limitation.rst.txt new file mode 100644 index 00000000..64444d6a --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/limitation.rst.txt @@ -0,0 +1,188 @@ +Replica Exchange Monte Carlo search with limitation +================================================================ + +This tutorial describes the constraint expression function that can be set in the ``[runner.limitation]`` section. +As an example, the replica exchange Monte Carlo method is applied to the minimization problem of Himmelblau function with constraints. + +Sample files location +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sample files are available in the ``sample/analytical/limitation`` directory. +This directory contains the following files. + +- ``input.toml`` + + Input file for the main program. + +- ``ref.txt`` + + File to check if the calculation is executed correctly (answer to obtain by performing this tutorial). + +- ``do.sh`` + + Script prepared to calculate this tutorial at once. + +In the following, we will explain these files, and then introduce the actual calculation results. + +Input files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following ``input.toml`` is an input file for the main program. + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "exchange" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + unit_list = [0.3, 0.3] + + [algorithm.exchange] + Tmin = 1.0 + Tmax = 100000.0 + numsteps = 10000 + numsteps_exchange = 100 + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.limitation] + co_a = [[1, -1],[1, 1]] + co_b = [[0], [-1]] + +``[base]`` section is the parameter of the main program. + +- ``dimension`` is the number of variables to be optimized, and in this case, it is 2. + +- ``output`` is the name of directory for the output files. + +``[algorithm]`` section is the section to set the search algorithm. + +- ``name`` is the name of the search algorithm. In this case, specify ``"exchange"`` for the replica exchange Monte Carlo method. + +- ``seed`` is the seed given to the pseudo-random number generator. + +``[algorithm.param]`` sub-section specifies the range of parameters to be optimized. + +- ``min_list`` and ``max_list`` specifies the lower bound and upper bound of the parameter space, respectively. + +- ``unit_list`` is step length in one MC update (deviation of Gaussian distribution). + +``[algorithm.exchange]`` sub-section specifies the hyperparameters of the replica exchange Monte Carlo method. + +- ``numstep`` is the number of Monte Carlo updates. + +- ``numsteps_exchange`` specifies the number of times to attempt temperature exchange. + +- ``Tmin`` and ``Tmax`` are the lower and upper limits of the temperature, respectively. + +- If ``Tlogspace`` is ``true``, the temperature is divided equally in log space. This option is not specified in this ``input.toml`` because the default value is ``true``. + +``[solver]`` section specifies the solver used internally in the main program. +In this case, the ``analytical`` solver is specified. +The ``analytical`` solver takes an extra parameter ``function_name`` that specifies the name of the function. In this case, the Himmelblau function is specified. + +``[runner]`` section has a sub-section ``[runner.limitation]``, and in this section, the constraint expression is set. +In the current version, the constraint expression is defined as :math:`Ax+b>0` where :math:`x` is :math:`N` dimensional input parameter, :math:`A` is a :math:`M \times N` matrix, and :math:`b` is a :math:`M` dimensional vector. +:math:`A` and :math:`b` are set by ``co_a`` and ``co_b``, respectively. +For details, see the ``[limitation]`` section in the input file in the manual. + +In this case, the following constraint is imposed: + +.. math:: + + x_{1} - x_{2} > 0 \\ + x_{1} + x_{2} - 1 > 0 + + +Calculation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample file is located. (It is assumed that you are directly under the directory where you downloaded this software.) + +.. code-block:: + + $ cd sample/analytical/limitation + +Then, execute the main program as follows. The calculation will end in about 20 seconds on a normal PC. + +.. code-block:: + + $ mpiexec -np 10 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +In this case, a calculation with 10 MPI parallel processes is performed. +When using OpenMPI, if the number of processes to be used is greater than the number of available cores, add the ``--oversubscribe`` option to the ``mpiexec`` command. +After executed, the ``output`` folder is generated, and there a subfolder for each MPI rank is created. + +Each subfolder contains the results of the calculation. +``trial.txt`` file, which contains the parameters and objective function values evaluated at each Monte Carlo step, and ``result.txt`` file, which contains the parameters actually adopted, are created. + +Both files have the same format, with the first two columns being the step number and the walker number within the process, the next being the temperature, the third being the value of the objective function, and the fourth and subsequent being the parameters. +The following is the beginning of the ``output/0/result.txt`` file: + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569 + 1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + +Finally, the best parameter and the rank and Monte Carlo step at which the objective function is minimized are written to ``output/best_result.txt``. + +.. code-block:: + + nprocs = 10 + rank = 2 + step = 4523 + walker = 0 + fx = 0.00010188398524402734 + x1 = 3.584944906595298 + x2 = -1.8506985826548874 + +``do.sh`` is available as a script to calculate all at once. +Additionally, in ``do.sh``, the difference between ``best_result.txt`` and ``ref.txt`` is also compared. + +.. code-block:: bash + + #!/bin/bash + + mpiexec -np 10 --oversubscribe python3 ../../../src/odatse_main.py input.toml + + echo diff output/best_result.txt ref.txt + res=0 + diff output/best_result.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: best_result.txt and ref.txt differ + false + fi + +Visualization of the calculation result +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By visualizing the ``result.txt`` file, we can confirm that the search is only for coordinates that satisfy the constraint expression. +``hist2d_limitation_sample.py`` is prepared to visualize the 2D parameter space. +This generates a histogram of the posterior probability distribution in the ``_histogram`` folder. +The histogram is generated using the data obtained by discarding the first 1000 steps of the search as a burn-in period. + +.. code-block:: + + $ python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1 + +The figure shows the posterior probability distribution and the two lines :math:`x_{1} - x_{2} = 0`, :math:`x_{1} + x_{2} - 1 = 0`, and it is confirmed that the search is only for the range where :math:`x_{1} - x_{2} > 0`, :math:`x_{1} + x_{2} - 1 > 0`. + +.. figure:: ../../../common/img/res_limitation.* + + Plots of sampled parameters and probability distribution. The horizontal and vertical axes denote ``x1`` and ``x2``, respectively. diff --git a/manual/v3.0.0/en/_sources/tutorial/mapper.rst.txt b/manual/v3.0.0/en/_sources/tutorial/mapper.rst.txt new file mode 100644 index 00000000..9329800d --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/mapper.rst.txt @@ -0,0 +1,135 @@ +Grid search +===================================== + +In this section, we will explain how to perform a grid-type search and analyze the minimization problem of Himmelblau function. +The grid type search is compatible with MPI. The specific calculation procedure is the same as for ``minsearch``. +The search grid is generated within the program from the input parameters, instead of passing the predefined ``MeshData.txt`` to the program. + + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/analytical/mapper``. +The following files are stored in the folder + +- ``input.toml`` + + Input file of the main program. + +- ``plot_colormap_2d.py`` + + Program to visualize the calculation results. + +- ``do.sh`` + + Script prepared for bulk calculation of this tutorial. + + +Input file +~~~~~~~~~~~~~~~~~~~ + +This section describes the input file for the main program, ``input.toml``. +The details of ``input.toml`` can be found in the input file section of the manual. + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.log] + interval = 20 + + [algorithm] + name = "mapper" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + +The contents of ``[base]``, ``[solver]``, and ``[runner]`` sections are the same as those for the search by the Nelder-Mead method (``minsearch``). + +``[algorithm]`` section specifies the algorithm to use and its settings. + +- ``name`` is the name of the algorithm you want to use. In this tutorial we will use ``mapper`` since we will be using grid-search method. + +In ``[algorithm.param]`` section, the parameters for the search grid are specified. + +- ``min_list`` and ``max_list`` are the minimum and the maximum values of each parameter. + +- ``num_list`` specifies the number of grid points along each parameter. + +For details on other parameters that are assumed by the default values in this tutorial and can be specified in the input file, please see the Input File chapter. + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located. (We assume that you are directly under the directory where you downloaded this software.) + +.. code-block:: + + $ cd sample/analytical/minsearch + +The, run the main program. The computation time takes only a few seconds on a normal PC. + +.. code-block:: + + $ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +Here, the calculation using MPI parallel with 4 processes will be done. +When executed, a folder for each rank will be created under ``output`` directory, and the calculation results of each rank will be written. +The standard output will be seen like this. + +.. code-block:: + + Make ColorMap + Iteration : 1/240 + Iteration : 2/240 + Iteration : 3/240 + Iteration : 4/240 + Iteration : 5/240 + Iteration : 6/240 + Iteration : 7/240 + ... + +Finally, the function values calculated for all the points on the grid will be written to ``output/ColorMap.txt``. +In this case, the following results will be obtained. + +.. code-block:: + + -6.000000 -6.000000 890.000000 + -5.600000 -6.000000 753.769600 + -5.200000 -6.000000 667.241600 + -4.800000 -6.000000 622.121600 + -4.400000 -6.000000 610.729600 + -4.000000 -6.000000 626.000000 + -3.600000 -6.000000 661.481600 + -3.200000 -6.000000 711.337600 + -2.800000 -6.000000 770.345600 + ... + +The first and second columns contain the values of ``x1`` and ``x2``, and the third column contains the function value. + + +Visualization of calculation results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By plotting ``ColorMap.txt``, we can estimate the region where the small function values are located. +A program ``plot_colormap_2d.py`` is prepared to generate such a plot of the two-dimensional space. + +.. code-block:: + + $ python3 plot_colormap_2d.py + +By executing the above command, ``ColorMapFig.png`` is generated in which the functional value evaluated at each grid point is shown as a color map on top of the contour of Himmelblau function. + +.. figure:: ../../../common/img/res_mapper.* + + Color map of the function values in the grid search of the two-dimensional parameter space. diff --git a/manual/v3.0.0/en/_sources/tutorial/minsearch.rst.txt b/manual/v3.0.0/en/_sources/tutorial/minsearch.rst.txt new file mode 100644 index 00000000..832d5e9c --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/minsearch.rst.txt @@ -0,0 +1,159 @@ +Optimization by Nelder-Mead method +==================================== + +In this section, we will explain how to calculate the minimization problem of Himmelblau function using the Nelder-Mead method. +The specific calculation procedure is as follows. + +1. Preparation of an input file + + Prepare an input file that describes parameters in TOML format. + +2. Run the main program + + Run the calculation using ``src/odatse_main.py`` to solve the minimization problem. + + +Location of the sample files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sample files are located in ``sample/analytical/minsearch``. +The following files are stored in the folder. + +- ``input.toml`` + + Input file of the main program. + +- ``do.sh`` + + Script prepared for doing all calculation of this tutorial + +In addition, ``plot_himmel.py`` in the ``sample`` folder is used to visualize the result. + + +Input file +~~~~~~~~~~~~~~~~~~~ + +In this section, we will prepare the input file ``input.toml`` for the main program. +The details of ``input.toml`` can be found in the ``input file`` section of the manual. + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.log] + interval = 20 + + [algorithm] + name = "minsearch" + seed = 12345 + + [algorithm.param] + min_list = [-6.0, -6.0] + max_list = [ 6.0, 6.0] + initial_list = [0, 0] + + +``[base]`` section describes parameters used in the whole program. + +- ``dimension`` is the number of variables to be optimized, in this case ``2`` since Himmelblau function is a two-variable function. + +- ``output_dir`` is the name of directory for output. + + +``[solver]`` section specifies the solver to be used inside the main program and its settings. + +- ``name`` is the name of the solver you want to use. In this tutorial, we perform analyses of an analytical function in the ``analytical`` solver. + +- ``function_name`` is the name of the function in the ``analytical`` solver. + +``[runner]`` section specifies settings on calling the direct problem solver from the inverse problem analysis algorithm. + +- ``interval`` in ``[runner.log]`` specifies the frequency of the log output. The logs are written in every ``interval`` steps. + +``[algorithm]`` section specifies the algorithm to use and its settings. + +- ``name`` is the name of the algorithm you want to use. In this tutorial we will use ``minsearch`` since we will be using the Nelder-Mead method. + +- ``seed`` specifies the initial input of random number generator. + +``[algorithm.param]`` section specifies the range of parameters to search and their initial values. + +- ``min_list`` and ``max_list`` specify the minimum and maximum values of the search range, respectively. + +- ``initial_list`` specifies the initial values. + +Other parameters, such as convergence judgments used in the Nelder-Mead method, can be done in the ``[algorithm]`` section, although they are omitted here because the default values are used. +See the input file chapter for details. + +Calculation execution +~~~~~~~~~~~~~~~~~~~~~~ + +First, move to the folder where the sample files are located. (We assume that you are directly under the directory where you downloaded this software.) + +.. code-block:: + + $ cd sample/analytical/minsearch + +Then, run the main program. The computation time takes only a few seconds on a normal PC. + +.. code-block:: + + $ python3 ../../../src/odatse_main.py input.toml | tee log.txt + +The standard output will be seen as follows. + +.. code-block:: + + Optimization terminated successfully. + Current function value: 0.000000 + Iterations: 40 + Function evaluations: 79 + iteration: 40 + len(allvecs): 41 + step: 0 + allvecs[step]: [0. 0.] + step: 1 + allvecs[step]: [0.375 0.375] + step: 2 + allvecs[step]: [0.0625 0.9375] + step: 3 + allvecs[step]: [0.65625 1.46875] + step: 4 + allvecs[step]: [0.328125 2.859375] + ... + +The ``x1`` and ``x2`` are the candidate parameters at each step and the function value at that point. +The final estimated parameters is written to ``output/res.dat``. +In the current case, the following result will be obtained: + +.. code-block:: + + fx = 4.2278370361994904e-08 + x1 = 2.9999669562950175 + x2 = 1.9999973389336225 + +It is seen that one of the minima is obtained. + +Visualization of calculation results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The steps taken during the search by the Nelder-Mead method is written in ``output/0/SimplexData.txt``. A tool to plot the path is prepared as ``simplex/plot_himmel.py``. + +.. code-block:: + + $ python3 ../plot_himmel.py --xcol=1 --ycol=2 --output=output/res.pdf output/0/SimplexData.txt + +By executing the above command, ``output/res.pdf`` will be generated. + +.. figure:: ../../../common/img/res_minsearch.* + + The path taken during the minimum search by the Nelder-Mead method is drawn by the blue line. The black curves show contour of Himmelblau function. + +The path of the minimum search by the Nelder-Mead method is drawn on top of the contour plot of Himmelblau function. Starting from the initial value at ``(0, 0)``, the path reaches to one of the minima, ``(3, 2)``. diff --git a/manual/v3.0.0/en/_sources/tutorial/pamc.rst.txt b/manual/v3.0.0/en/_sources/tutorial/pamc.rst.txt new file mode 100644 index 00000000..852ca5d1 --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/pamc.rst.txt @@ -0,0 +1,185 @@ +Optimization by population annealing +================================================ + +This tutorial describes how to estimate the optimization problem of Himmelblau function by using the population annealing Monte Carlo method (PAMC). + +Sample files +~~~~~~~~~~~~~~~~~~ + +Sample files are available from ``sample/analytical/pamc`` . +This directory includes the following files: + +- ``input.toml`` + + The input file of odatse + +- ``plot_result_2d.py`` + + Program to visualize the results + +- ``do.sh`` + + Script files for running this tutorial + + +Input files +~~~~~~~~~~~~~ + +This subsection describes the input file. +For details, see the input file section of the manual. + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.log] + interval = 20 + + [algorithm] + name = "pamc" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + step_list = [0.1, 0.1] + + [algorithm.pamc] + Tmin = 1.0 + Tmax = 100.0 + Tnum = 21 + Tlogspace = true + numsteps_annealing = 100 + nreplica_per_proc = 100 + +In the following, we will briefly describe this input file. +For details, see the manual of :doc:`../algorithm/pamc`. + +The contents of ``[base]``, ``[solver]``, and ``[runner]`` sections are the same as those for the search by the Nelder-Mead method (``minsearch``). + +``[algorithm]`` section specifies the algorithm to use and its settings. + +- ``name`` is the name of the algorithm you want to use In this tutorial we will use the population annealing Monte Carlo (PAMC) algorithm, so specify ``pamc``. + +- ``seed`` is the seed that a pseudo-random number generator uses. + +``[algorithm.param]`` section sets the parameter space to be explored. + +- ``min_list`` is a lower bound and ``max_list`` is an upper bound. + +- ``unit_list`` is step length in one Monte Carlo update (deviation of Gaussian distribution). + +``[algorithm.pamc]`` section sets the parameters for PAMC. + +- ``numsteps_annealing`` is the number of interval steps between temperature decreasing. + +- ``bmin``, ``bmax`` are the minimum and the maximum of inversed temperature, respectively. + +- ``Tnum`` is the number of (inversed) temperature points. + +- When ``Tlogspace`` is ``true``, the temperature points are distributed uniformly in the logarithmic space. + +- ``nreplica_per_proc`` is the number of replicas (MC walkers) in one MPI process. + + +Calculation +~~~~~~~~~~~~ + +First, move to the folder where the sample file is located. (Hereinafter, it is assumed that you are the root directory of ODAT-SE.) + +.. code-block:: + + $ cd sample/analytical/pamc + +Then, run the main program. It will take a few secondes on a normal PC. + +.. code-block:: + + $ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +Here, the calculation is performed using MPI parallel with 4 processes. +If you are using Open MPI and you request more processes than the number of cores, add the ``--oversubscribe`` option to the ``mpiexec`` command. + +When executed, a folder for each MPI rank will be created under the directory ``output``, and ``trial_TXXX.txt`` files containing the parameters evaluated in each Monte Carlo step and the value of the objective function at each temperature (``XXX`` is the index of points), and ``result_TXXX.txt`` files containing the parameters actually adopted will be created. +These files are concatnated into ``result.txt`` and ``trial.txt``. + +These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the (inversed) temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters. +The final two columns are the weight of walker (Neal-Jarzynski weight) and the index of the grand ancestor (the replica index at the beginning of the calculation). + +.. code-block:: + + # step walker T fx x1 x2 weight ancestor + 0 0 100.0 187.94429125133564 5.155393113805774 -2.203493345018569 1.0 0 + 0 1 100.0 3.179380982615041 -3.7929742598748666 -3.5452766573635235 1.0 1 + 0 2 100.0 108.25464277273859 0.8127003489802398 1.1465364357510186 1.0 2 + 0 3 100.0 483.84183395038843 5.57417423682746 1.8381251624588506 1.0 3 + 0 4 100.0 0.43633134370869153 2.9868796504069426 1.8428384502208246 1.0 4 + 0 5 100.0 719.7992581349758 2.972577711255287 5.535680832873856 1.0 5 + 0 6 100.0 452.4691017123836 -5.899340424701358 -4.722667479627368 1.0 6 + 0 7 100.0 45.5355817998709 -2.4155554347674215 1.8769341969872393 1.0 7 + 0 8 100.0 330.7972369561986 3.717750630491217 4.466110964691396 1.0 8 + 0 9 100.0 552.0479484091458 5.575771168463163 2.684224163039442 1.0 9 + 0 10 100.0 32.20027165958588 1.7097039347500953 2.609443449748964 1.0 10 + ... + + +``output/best_result.txt`` is filled with information about the parameter with the optimal objective function, the rank from which it was obtained, and the Monte Carlo step. + +.. code-block:: + + nprocs = 4 + rank = 3 + step = 1806 + walker = 74 + fx = 4.748689609377718e-06 + x1 = -2.805353724219707 + x2 = 3.131045687296453 + +Finally, ``output/fx.txt`` stores the statistics at each temperature point: + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.01 130.39908953806298 6.023477428315198 400 0.0 0.9378 + 0.01258925411794167 83.6274790817115 3.83620542622489 400 -0.2971072297035158 0.930325 + 0.015848931924611134 60.25390522675298 2.73578884504734 400 -0.5426399088244793 0.940375 + 0.01995262314968879 47.20146188151557 2.3479083531465976 400 -0.7680892360649545 0.93715 + 0.025118864315095794 41.118822390166315 1.8214854089575818 400 -0.9862114670289625 0.9153 + ... + +The first column is (inversed) temperature, and +the second/third ones are the mean and standard error of :math:`f(x)`, respectively. +The fourth column is the number of replicas and the fifth one is the logarithm of the ratio of the partition functions, :math:`\log(Z_n/Z_0)`, where :math:`Z_0` is the partition function at the first temperature. +The sixth column is the acceptance ratio of MC updates. + + +Visualization +~~~~~~~~~~~~~~~~~~~ + +By illustrating ``result_T.txt``, you can estimate regions where the function values become small. +In this case, the figure ``result_fx.pdf`` and ``result_T.pdf`` of the 2D parameter space is created by using the following command. +The color of symbols of ``result_fx.pdf`` and ``result_T.pdf`` mean ``R-factor`` and :math:`\beta`, respectively. + +By executing the following command, the figures of two-dimensional parameter space ``res_T%.png`` will be generated where ``%`` stands for the indices of temperature. The symbol color corresponds to the function value. + +.. code-block:: + + $ python3 plot_result_2dmap.py + +It is seen from the figures that the samples are concentrated near the minima of ``f(x)`` where the objective function has a small value. + +.. figure:: ../../../common/img/res_pamc.* + + Plot of sampled parameters. The horizontal axis denotes ``x1``, the vertical axis denotes ``x2``, and the color represents the value of ``T`` (left) and ``f(x)`` (right), respectively. diff --git a/manual/v3.0.0/en/_sources/tutorial/solver_simple.rst.txt b/manual/v3.0.0/en/_sources/tutorial/solver_simple.rst.txt new file mode 100644 index 00000000..663d58e4 --- /dev/null +++ b/manual/v3.0.0/en/_sources/tutorial/solver_simple.rst.txt @@ -0,0 +1,94 @@ +Adding a direct problem solver +===================================== + +Solver for benchmarking, ``analytical`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ODAT-SE provides the ``analytical`` solver as a direct problem solver that can be used to test search algorithms. + +To use the ``analytical`` solver, the users may set the ``name`` parameter in the ``[solver]`` section to ``"analytical"``, and choose the benchmark function ``f(x)`` in the ``function_name`` parameter. +For example, to use Himmelblau function, make an input file including the following lines: + +.. code-block:: toml + + [solver] + name = "analytical" + function_name = "himmelblau" + +For details of ``analytical`` solver, see :doc:`the reference of the analytical solver <../solver/analytical>`. + + +How to add a direct problem solver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The easiest way to define and analyze a user-defined direct problem solver is to add it to the ``analytical`` solver as a function. +As an example, we will explain the case of adding `the Booth function `_: + +.. math:: + + f(x,y) = (x+2y-7)^2 + (2x+y-5)^2. + +(The minimum point is :math:`f(1,3) = 0`.) + +To do so, we need to download the source code of ODAT-SE and edit the file of ``analytical`` solver. +For instructions on how to download the source code and run ``odatse`` from the source code, see :doc:`how to install <../start>`. +``analytical`` solver is defined in the ``src/odatse/solver/analytical.py``, so we will edit this. + +First, define the booth function as follows: + +.. code-block:: python + + def booth(xs: np.ndarray) -> float: + """Booth function + + it has one global minimum f(xs) = 0 at xs = [1,3]. + """ + + if xs.shape[0] != 2: + raise RuntimeError( + f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one" + ) + return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2 + +Next, insert the following code in the if branch of the ``Solver`` class's constructor (``__init__``) to allow users to choose the ``booth`` function by the ``solver.function_name`` parameter of the input file. + +.. code-block:: python + + elif function_name == "booth": + self.set_function(booth) + +With this modified ``analytical`` solver, you can optimize the Booth function. +For example, to optimize it by the Nelder-Mead method, pass the following input file (``input.toml``): + +.. code-block:: toml + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "minsearch" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + initial_list = [0, 0] + + [solver] + name = "analytical" + function_name = "booth" + +to ``src/odatse_main.py`` script as follows: + +.. code-block:: bash + + $ python3 src/odatse_main.py input.toml + + ... skipped ... + + Iterations: 38 + Function evaluations: 75 + Solution: + x1 = 1.0000128043523089 + x2 = 2.9999832920260863 diff --git a/manual/v3.0.0/en/_static/alert_info_32.png b/manual/v3.0.0/en/_static/alert_info_32.png new file mode 100644 index 00000000..ea4d1baf Binary files /dev/null and b/manual/v3.0.0/en/_static/alert_info_32.png differ diff --git a/manual/v3.0.0/en/_static/alert_warning_32.png b/manual/v3.0.0/en/_static/alert_warning_32.png new file mode 100644 index 00000000..a687c3dc Binary files /dev/null and b/manual/v3.0.0/en/_static/alert_warning_32.png differ diff --git a/manual/v3.0.0/en/_static/basic.css b/manual/v3.0.0/en/_static/basic.css new file mode 100644 index 00000000..944485b9 --- /dev/null +++ b/manual/v3.0.0/en/_static/basic.css @@ -0,0 +1,914 @@ +/* + * Sphinx stylesheet -- basic theme. + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin-top: 10px; +} + +ul.search li { + padding: 5px 0; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 59em; + max-width: 70em; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/manual/v3.0.0/en/_static/bg-page.png b/manual/v3.0.0/en/_static/bg-page.png new file mode 100644 index 00000000..fe0a6dc8 Binary files /dev/null and b/manual/v3.0.0/en/_static/bg-page.png differ diff --git a/manual/v3.0.0/en/_static/bullet_orange.png b/manual/v3.0.0/en/_static/bullet_orange.png new file mode 100644 index 00000000..1cb8097c Binary files /dev/null and b/manual/v3.0.0/en/_static/bullet_orange.png differ diff --git a/manual/v3.0.0/en/_static/doctools.js b/manual/v3.0.0/en/_static/doctools.js new file mode 100644 index 00000000..0398ebb9 --- /dev/null +++ b/manual/v3.0.0/en/_static/doctools.js @@ -0,0 +1,149 @@ +/* + * Base JavaScript utilities for all Sphinx HTML documentation. + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/manual/v3.0.0/en/_static/documentation_options.js b/manual/v3.0.0/en/_static/documentation_options.js new file mode 100644 index 00000000..a2fde81a --- /dev/null +++ b/manual/v3.0.0/en/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '3.0-dev', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/manual/v3.0.0/en/_static/file.png b/manual/v3.0.0/en/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/manual/v3.0.0/en/_static/file.png differ diff --git a/manual/v3.0.0/en/_static/haiku.css b/manual/v3.0.0/en/_static/haiku.css new file mode 100644 index 00000000..8b2e7581 --- /dev/null +++ b/manual/v3.0.0/en/_static/haiku.css @@ -0,0 +1,369 @@ +/* + * Sphinx stylesheet -- haiku theme. + * + * Adapted from https://haiku-os.org/docs/Haiku-doc.css. + * Original copyright message: + * + * Copyright 2008-2009, Haiku. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Francois Revol + * Stephan Assmus + * Braden Ewing + * Humdinger + * + */ + +@import url("basic.css"); + +html { + margin: 0px; + padding: 0px; + background: #FFF url(bg-page.png) top left repeat-x; +} + +body { + line-height: 1.5; + margin: auto; + padding: 0px; + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; + min-width: 59em; + max-width: 70em; + color: #333333; +} + +div.footer { + padding: 8px; + font-size: 11px; + text-align: center; + letter-spacing: 0.5px; +} + +/* link colors and text decoration */ + +a:link { + font-weight: bold; + text-decoration: none; + color: #dc3c01; +} + +a:visited { + font-weight: bold; + text-decoration: none; + color: #551a8b; +} + +a:hover, a:active { + text-decoration: underline; + color: #ff4500; +} + +/* Some headers act as anchors, don't give them a hover effect */ + +h1 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h2 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h3 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h4 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +a.headerlink { + color: #a7ce38; + padding-left: 5px; +} + +a.headerlink:hover { + color: #a7ce38; +} + +/* basic text elements */ + +div.content { + margin-top: 20px; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 50px; + font-size: 0.9em; +} + +/* heading and navigation */ + +div.header { + position: relative; + left: 0px; + top: 0px; + height: 85px; + /* background: #eeeeee; */ + padding: 0 40px; +} +div.header h1 { + font-size: 1.6em; + font-weight: normal; + letter-spacing: 1px; + color: #0c3762; + border: 0; + margin: 0; + padding-top: 15px; +} +div.header h1 a { + font-weight: normal; + color: #0c3762; +} +div.header h2 { + font-size: 1.3em; + font-weight: normal; + letter-spacing: 1px; + text-transform: uppercase; + color: #aaa; + border: 0; + margin-top: -3px; + padding: 0; +} + +div.header img.rightlogo { + float: right; +} + + +div.title { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-bottom: 25px; +} +div.topnav { + /* background: #e0e0e0; */ +} +div.topnav p { + margin-top: 0; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 0px; + text-align: right; + font-size: 0.8em; +} +div.bottomnav { + background: #eeeeee; +} +div.bottomnav p { + margin-right: 40px; + text-align: right; + font-size: 0.8em; +} + +a.uplink { + font-weight: normal; +} + + +/* contents box */ + +table.index { + margin: 0px 0px 30px 30px; + padding: 1px; + border-width: 1px; + border-style: dotted; + border-color: #e0e0e0; +} +table.index tr.heading { + background-color: #e0e0e0; + text-align: center; + font-weight: bold; + font-size: 1.1em; +} +table.index tr.index { + background-color: #eeeeee; +} +table.index td { + padding: 5px 20px; +} + +table.index a:link, table.index a:visited { + font-weight: normal; + text-decoration: none; + color: #dc3c01; +} +table.index a:hover, table.index a:active { + text-decoration: underline; + color: #ff4500; +} + + +/* Haiku User Guide styles and layout */ + +/* Rounded corner boxes */ +/* Common declarations */ +div.admonition { + -webkit-border-radius: 10px; + -khtml-border-radius: 10px; + -moz-border-radius: 10px; + border-radius: 10px; + border-style: dotted; + border-width: thin; + border-color: #dcdcdc; + padding: 10px 15px 10px 15px; + margin-bottom: 15px; + margin-top: 15px; +} +div.note { + padding: 10px 15px 10px 80px; + background: #e4ffde url(alert_info_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.warning { + padding: 10px 15px 10px 80px; + background: #fffbc6 url(alert_warning_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.seealso { + background: #e4ffde; +} + +/* More layout and styles */ +h1 { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h2 { + font-size: 1.2em; + font-weight: normal; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h3 { + font-size: 1.1em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +h4 { + font-size: 1.0em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +p { + text-align: justify; +} + +p.last { + margin-bottom: 0; +} + +ol { + padding-left: 20px; +} + +ul { + padding-left: 5px; + margin-top: 3px; +} + +li { + line-height: 1.3; +} + +div.content ul > li { + -moz-background-clip:border; + -moz-background-inline-policy:continuous; + -moz-background-origin:padding; + background: transparent url(bullet_orange.png) no-repeat scroll left 0.45em; + list-style-image: none; + list-style-type: none; + padding: 0 0 0 1.666em; + margin-bottom: 3px; +} + +td { + vertical-align: top; +} + +code { + background-color: #e2e2e2; + font-size: 1.0em; + font-family: monospace; +} + +pre { + border-color: #0c3762; + border-style: dotted; + border-width: thin; + margin: 0 0 12px 0; + padding: 0.8em; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +/* printer only pretty stuff */ +@media print { + .noprint { + display: none; + } + /* for acronyms we want their definitions inlined at print time */ + acronym[title]:after { + font-size: small; + content: " (" attr(title) ")"; + font-style: italic; + } + /* and not have mozilla dotted underline */ + acronym { + border: none; + } + div.topnav, div.bottomnav, div.header, table.index { + display: none; + } + div.content { + margin: 0px; + padding: 0px; + } + html { + background: #FFF; + } +} + +.viewcode-back { + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; + margin: -1px -10px; + padding: 0 12px; +} + +/* math display */ +div.math p { + text-align: center; +} \ No newline at end of file diff --git a/manual/v3.0.0/en/_static/language_data.js b/manual/v3.0.0/en/_static/language_data.js new file mode 100644 index 00000000..c7fe6c6f --- /dev/null +++ b/manual/v3.0.0/en/_static/language_data.js @@ -0,0 +1,192 @@ +/* + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/manual/v3.0.0/en/_static/minus.png b/manual/v3.0.0/en/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/manual/v3.0.0/en/_static/minus.png differ diff --git a/manual/v3.0.0/en/_static/plus.png b/manual/v3.0.0/en/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/manual/v3.0.0/en/_static/plus.png differ diff --git a/manual/v3.0.0/en/_static/pygments.css b/manual/v3.0.0/en/_static/pygments.css new file mode 100644 index 00000000..0d49244e --- /dev/null +++ b/manual/v3.0.0/en/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #eeffcc; } +.highlight .c { color: #408090; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #333333 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #208050 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #208050 } /* Literal.Number.Bin */ +.highlight .mf { color: #208050 } /* Literal.Number.Float */ +.highlight .mh { color: #208050 } /* Literal.Number.Hex */ +.highlight .mi { color: #208050 } /* Literal.Number.Integer */ +.highlight .mo { color: #208050 } /* Literal.Number.Oct */ +.highlight .sa { color: #4070a0 } /* Literal.String.Affix */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #06287e } /* Name.Function.Magic */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ +.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/manual/v3.0.0/en/_static/searchtools.js b/manual/v3.0.0/en/_static/searchtools.js new file mode 100644 index 00000000..2c774d17 --- /dev/null +++ b/manual/v3.0.0/en/_static/searchtools.js @@ -0,0 +1,632 @@ +/* + * Sphinx JavaScript utilities for the full-text search. + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + SearchResultKind.title, + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + SearchResultKind.text, + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/manual/v3.0.0/en/_static/sphinx_highlight.js b/manual/v3.0.0/en/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/manual/v3.0.0/en/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/manual/v3.0.0/en/acknowledgement.html b/manual/v3.0.0/en/acknowledgement.html new file mode 100644 index 00000000..f2036a50 --- /dev/null +++ b/manual/v3.0.0/en/acknowledgement.html @@ -0,0 +1,63 @@ + + + + + + + + Acknowledgements — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Acknowledgements

+

The development of 2DMAT and ODAT-SE was supported by JSPS KAKENHI Grant Numbers 19H04125, 20H00581, 21K19773, and 23K18465, and “Project for advancement of software usability in materials science” (FY2020, 2021, and 2024) of The Institute for Solid State Physics, The University of Tokyo.

+

A part of the design of and naming in software is inspired by abics. +For adding a tutorial for customizing solver, we thank to K. Tsukamoto (ISSP).

+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/algorithm/bayes.html b/manual/v3.0.0/en/algorithm/bayes.html new file mode 100644 index 00000000..f0ca11e2 --- /dev/null +++ b/manual/v3.0.0/en/algorithm/bayes.html @@ -0,0 +1,213 @@ + + + + + + + + Bayesian optimization bayes — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Bayesian optimization bayes

+

bayes is an Algorithm that uses Bayesian optimization to perform parameter search. +The implementation is based on PHYSBO.

+
+

Preparation

+

You will need to install PHYSBO beforehand.

+
$ python3 -m pip install physbo
+
+
+

If mpi4py is installed, MPI parallel computing is possible.

+
+
+

Input parameters

+
+

[algorithm.param] section

+

In this section, the search parameter space is defined.

+

If mesh_path is defined, it will be read from a mesh file. +In a mesh file, one line gives one point in the parameter space, +the first column is the data number, and the second and subsequent columns are the coordinates of each dimension.

+

If mesh_path is not defined, min_list, max_list, and num_list are used to create an evenly spaced grid for each parameter.

+
    +

  • mesh_path

    +

    Format: String

    +

    Description: The path to a reference file that contains information about the mesh data.

    +
    • +

  • min_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: The minimum value the parameter can take.

    +
    • +

  • max_list

    +

    Format: List of float.The length should match the value of dimension.

    +

    Description: The maximum value the parameter can take.

    +
    • +

  • num_list

    +

    Format: List of integer. The length should match the value of dimension.

    +

    Description: The number of grids the parametar can take at each dimension.

    +
    • +
+
+
+

[algorithm.bayes] section

+

The hyper parameters are defined.

+
    +

  • random_max_num_probes

    +

    Format: Integer (default: 20)

    +

    Description: Number of random samples to be taken before Bayesian optimization (random sampling is needed if parameters and scores are not available at the beginning).

    +
    • +

  • bayes_max_num_probes

    +

    Format: Integer (default: 40)

    +

    Description: Number of times to perform Bayesian optimization.

    +
    • +

  • score

    +

    Format: String (default: TS )

    +

    Description: Parameter to specify the score function. +EI (expected improvement), PI (probability of improvement), and TS (Thompson sampling) can be chosen.

    +
    • +

  • interval

    +

    Format: Integer (default: 5)

    +

    Description: The hyperparameters are learned at each specified interval. If a negative value is specified, no hyperparameter learning will be performed. +If a value of 0 is specified, hyperparameter learning will be performed only in the first step.

    +
    • +

  • num_rand_basis

    +

    Format: Integer (default: 5000)

    +

    Description: Number of basis functions; if 0 is specified, the normal Gaussian process is performed without using the Bayesian linear model.

    +
    • +
+
+
+
+

Reference file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables defined in string_list in the [solver.param] section.

+

Below, a sample file is shown.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

Output files

+
+

BayesData.txt

+

At each step of the optimization process, the values of the parameters and the corresponding objective functions are listed in the order of the optimal parameters so far and the searched parameters at that step.

+
#step z1 z2 R-factor z1_action z2_action R-factor_action
+0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885
+1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033
+2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189
+3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794
+...
+
+
+
+
+
+

Restart

+

The execution mode is specified by the run_mode parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to --init, --resume, and --cont options of odatse command, respectively.

+
    +

  • "initial" (default)

    +

    The program is started from the initial state. +First, it performs the random sampling for the number of times specified by random_max_num_probes parameter. +Then, it performs the Bayes optimization for the number of times specified by bayes_max_num_probes.

    +

    If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions:

    +
      +

    1. when the random sampling is finished.

      2. +

    2. during the Bayesian optimization, the specified number of iteration has been done, or the specified period of time has passed.

      3. +

    3. at the end of the execution.

      4. +
    +
    • +

  • "resume"

    +

    The program execution is resumed from the latest checkpoint. +The conditions such as the number of MPI processes should be kept the same.

    +

    It is noted that the results obtaind from the resumed run from the interruption and those obtained from the uninterrupted run do not exactly match.

    +
    • +

  • "continue"

    +

    The program execution of the Bayes optimization is continued from the previous run. +The value of bayes_max_num_probes should be increased. The step counter is taken over.

    +

    For example: in the first run, the calculation is carried out for 100 Bayesian optimization steps with bayes_max_num_probes=100. In the next run, the calculation is continued with bayes_max_num_probes=200, where the calculations from 101st step to 200th step are carried out.

    +
    • +
+
+
+

Algorithm Description

+

Bayesian optimization (BO) is an optimization algorithm that uses machine learning as an aid, and is particularly powerful when it takes a long time to evaluate the objective function.

+

In BO, the objective function \(f(\vec{x})\) is approximated by a model function (often a Gaussian process) \(g(\vec{x})\) that is quick to evaluate and easy to optimize. +The \(g\) is trained to reproduce well the value of the objective function \(\{\vec{x}_i\}_{i=1}^N\) at some suitably predetermined points (training data set) \(\{f(\vec{x}_i)\}_{i=1}^N\).

+

At each point in the parameter space, we propose the following candidate points for computation \(\vec{x}_{N+1}\), where the expected value of the trained \(g(\vec{x})\) value and the “score” (acquition function) obtained from the error are optimal. +The training is done by evaluating \(f(\vec{x}_{N+1})\), adding it to the training dataset, and retraining \(g\). +After repeating these searches, the best value of the objective function as the optimal solution will be returned.

+

A point that gives a better expected value with a smaller error is likely to be the correct answer, +but it does not contribute much to improving the accuracy of the model function because it is considered to already have enough information. +On the other hand, a point with a large error may not be the correct answer, +but it is a place with little information and is considered to be beneficial for updating the model function. +Selecting the former is called “exploition,” while selecting the latter is called “exploration,” and it is important to balance both. +The definition of “score” defines how to choose between them.

+

In ODAT-SE, we use PHYSBO as a library for Bayesian optimization. +PHYSBO, like mapper_mpi, computes a “score” for a predetermined set of candidate points, and proposes an optimal solution. +MPI parallel execution is possible by dividing the set of candidate points. +In addition, we use a kernel that allows us to evaluate the model function and thus calculate the “score” with a linear amount of computation with respect to the number of training data points \(N\). +In PHYSBO, “expected improvement (EI)”, “probability of improvement (PI)”, and “Thompson sampling (TS)” are available as “score” functions.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/algorithm/exchange.html b/manual/v3.0.0/en/algorithm/exchange.html new file mode 100644 index 00000000..e4865248 --- /dev/null +++ b/manual/v3.0.0/en/algorithm/exchange.html @@ -0,0 +1,368 @@ + + + + + + + + Replica exchange Monte Carlo exchange — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Replica exchange Monte Carlo exchange

+

exchange explores the parameter space by using the replica exchange Monte Carlo (RXMC) method.

+
+

Preparation

+

mpi4py should be installed if MPI parallelization is used.

+
$ python3 -m pip install mpi4py
+
+
+
+
+

Input parameters

+

This has two subsections algorithm.param and algorithm.exchange .

+
+

[algorithm.param]

+

This defines a space to be explored. +When mesh_path key is defined the discrete space is used. +Otherwise, continuous space is used.

+
    +

  • Continuous space

    +
      +

    • initial_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: Initial value of parameters. +If not defined, these will be initialize randomly.

      +
      • +

    • min_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +Minimum value of each parameter. +When a parameter falls below this value during the Monte Carlo search, +the solver is not evaluated and the value is considered infinite.

      +
      • +

    • max_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +Maximum value of each parameter. +When a parameter exceeds this value during the Monte Carlo search, +the solver is not evaluated and the value is considered infinite.

      +
      • +

    • step_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +The step length in one Monte Carlo update (deviation of Gaussian distribution).

      +
      • +
    +
    • +

  • Discrete space

    +
      +

    • mesh_path

      +

      Format: string

      +

      Description: Path to the mesh definition file.

      +
      • +

    • neighborlist_path

      +

      Format: string

      +

      Description: Path to the neighborhood-list file.

      +
      • +
    +
    • +
+
+
+

[algorithm.exchange]

+
    +

  • numsteps

    +

    Format: Integer

    +

    Description: The number of Monte Carlo steps.

    +
    • +

  • numsteps_exchange

    +

    Format: Integer

    +

    Description: The number of interval Monte Carlo steps between replica exchange.

    +
    • +

  • Tmin

    +

    Format: Float

    +

    Description: The minimum value of the “temperature” (\(T\)).

    +
    • +

  • Tmax

    +

    Format: Float

    +

    Description: The maximum value of the “temperature” (\(T\)).

    +
    • +

  • bmin

    +

    Format: Float

    +

    Description: The minimum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • bmax

    +

    Format: Float

    +

    Description: The maximum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • Tlogspace

    +

    Format: Boolean (default: true)

    +

    Description: Whether to assign “temperature” to replicas equally spaced in the logarithmic space or not.

    +
    • +

  • nreplica_per_proc

    +

    Format: Integer (default: 1)

    +

    Description: The number of replicas in a MPI process.

    +
    • +
+
+
+
+

Reference file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this “algorithm”.

+

Below, a sample file is shown.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

Neighborhood-list file

+

Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define “neighborhoods” for each point \(i\), which are points that a walker can move from \(i\) +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point \(i\) is specified by the first column, +and the indices of final points \(j\) are specified by the second and successive columns.

+

An utility tool, odatse_neighborlist is available for generating a neighborhood-list file from a mesh file. For details, please see Related Tools.

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

Output files

+
+

RANK/trial.txt

+

This file stores the suggested parameters and the corresponding value returned from the solver for each replica. +The first column is the index of the MC step. +The second column is the index of the walker in the process. +The third column is the temperature of the replica. +The fourth column is the value of the solver. +The remaining columns are the coordinates.

+

Example:

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861
+2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

RANK/result.txt

+

This file stores the sampled parameters and the corresponding value returned from the solver for each replica. +This has the same format as trial.txt.

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

best_result.txt

+

The optimal value of the solver and the corresponding parameter among the all samples.

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

result_T#.txt

+

This file stores samples for each temperature ( # is replaced with the index of temperature ). +The first column is the index of the MC step. +The second column is the index of the walker. +The third column is the value of the solver. +The remaining columns are the coordinates.

+
# T = 1.0
+0 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+1 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+2 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+3 15 28.98676409223712 3.7442621319489637 -3.868754990884034
+
+
+
+
+
+

Restart

+

The execution mode is specified by the run_mode parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to --init, --resume, and --cont options of odatse command, respectively.

+
    +

  • "initial" (default)

    +

    The program is started from the initialized state. +If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions:

    +
      +

    1. the specified number of steps has been done, or the specified period of time has passed.

      2. +

    2. at the end of the execution.

      3. +
    +
    • +

  • "resume"

    +

    The program execution is resumed from the latest checkpoint. +The conditions such as the number of MPI processes should be kept the same.

    +
    • +

  • "continue"

    +

    The program execution is continued from the previous run. +The value of numsteps should be increased. The step counter is taken over.

    +

    For example: in the first run, the calculation is carried out for 1000 steps with numsteps = 1000. In the next run, the calculation is continued with numsteps = 2000, where the calculations from 1001st step to 2000th step are carried out.

    +
    • +
+
+
+

Algorithm

+
+

Markov chain Monte Carlo

+

The Markov chain Monte Carlo (MCMC) sampling explores the parameter space by moving walkers \(\vec{x}\) stochastically according to the weight function \(W(\vec{x})\). +For the weight function, the Boltzmann factor \(W(\vec{x}) = e^{-f(\vec{x})/T}\) is generally adopted, where \(T>0\) is the “temperature.” +It is impossible in the many cases, unfortunately, to sample walkers according to \(W\) directly. +Insteadly, the MCMC method moves walkers slightly and generates a time series \(\{\vec{x}_t\}\) such that the distribution of the walkers obeys \(W\) . +Let us call the transision probability from \(\vec{x}\) to \(\vec{x}'\) as \(p(\vec{x}' | \vec{x})\). +When \(p\) is determined by the following condition (“the balance condition”)

+
+\[W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x}),\]
+

the distribution of the generated time series \(\{\vec{x}_t\}\) will converges to \(W(\vec{x})\) [1]. +Practically, the stronger condition (“the detailed balance condition”)

+
+\[p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x})\]
+

is usually imposed. +The detailed balance condition returns to the balance condition by taking the summation of \(\vec{x}\).

+

ODAT-SE adopts the Metropolis-Hasting (MH) method for solving the detailed balance condition. +The MH method splits the transition process into the suggestion process and the acceptance process.

+
    +

  1. Generate a candidate \(\vec{x}\) with the suggestion probability \(P(\vec{x} | \vec{x}_t)\).

    +
      +

    • As \(P\), use a simple distribution such as the normal distribution with centered at x.

      • +
    +
    2. +

  2. Accept the candidate \(\vec{x}\) with the acceptance probability \(Q(\vec{x} | \vec{x}_t)\).

    +
      +

    • If accepted, let \(\vec{x}_{t+1}\) be vec{x}.

      • +

    • Otherwise, let \(\vec{x}_{t+1}\) be vec{x}_t.

      • +
    +
    3. +
+

The whole transision probability is the product of these two ones, \(p(\vec{x} | \vec{x_t}) = P(\vec{x} | \vec{x}_t) Q(\vec{x} | \vec{x}_t)\). +The acceptance probability \(Q(\vec{x} | \vec{x}_t)\) is defined as

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right].\]
+

It is easy to verify that the detailed balance condition is satisfied by substituting it into the detailed balance condition equation.

+

When adopting the Boltzmann factor for the weight and a symmetry distribution +\(P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})\) for the suggestion probability, +the acceptance probability \(Q\) will be the following simple form:

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right].\]
+

By saying \(\Delta f = f(\vec{x}) - f(\vec{x}_t)\) and using the fact \(Q=1\) for \(\Delta f \le 0\), +the procedure of MCMC with the MH algorithm is the following:

+
    +

  1. Choose a candidate from near the current position and calculate \(f\) and \(\Delta f\).

    2. +

  2. If \(\Delta f \le 0\), that is, the walker is descending, accept it.

    3. +

  3. Otherwise, accept it with the probability \(Q=e^{-\Delta f/T}\).

    4. +

  4. Repeat 1-3.

    5. +
+

The solution is given as the point giving the minimum value of \(f(\vec{x})\). +The third process of the above procedure endures that walkers can climb over the hill with a height of \(\Delta f \sim T\), the MCMC sampling can escape from local minima.

+
+
+

Replica exchange Monte Carlo

+

The “temperature” \(T\) is one of the most important hyper parameters in the MCMC sampling. +The MCMC sampling can climb over the hill with a height of \(T\) but cannot easily escape from the deeper valley than \(T\). +It is why we should increase the temperature in order to avoid stuck to local minima. +On the other hand, since walkers cannot see the smaller valleys than \(T\), the precision of the obtained result \(\min f(\vec{x})\) becomes about \(T\), and it is necessary to decrease the temperature in order to achieve more precise result. +This dilemma leads us that we should tune the temperature carefully.

+

One of the ways to overcome this problem is to update temperature too. +For example, simulated annealing decreases temperature as the iteration goes. +Another algorithm, simulated tempering, treats temperature as another parameter to be sampled, not a fixed hyper parameter, +and update temperature after some iterations according to the (detailed) balance condition. +Simulated tempering studies the details of a valley by cooling and escapes from a valley by heating. +Replica exchange Monte Carlo (RXMC), also known as parallel tempering, is a parallelized version of the simulated tempering. +In this algorithm, several copies of a system with different temperature, called as replicas, will be simulated in parallel. +Then, with some interval of steps, each replica exchanges temperature with another one according to the (detailed) balance condition. +As the simulated tempering does, RXMC can observe the details of a valley and escape from it by cooling and heating. +Moreover, because each temperature is assigned to just one replica, the temperature distribution will not be biased. +Using more replicas narrows the temperature interval, and increases the acceptance ratio of the temperature exchange. +This is why this algorithm suits for the massively parallel calculation.

+

It is recommended that users perform minsearch optimization starting from the result of exchange, because the RXMC result has uncertainty due to temperature.

+

footnote

+ +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/algorithm/index.html b/manual/v3.0.0/en/algorithm/index.html new file mode 100644 index 00000000..99a076d8 --- /dev/null +++ b/manual/v3.0.0/en/algorithm/index.html @@ -0,0 +1,72 @@ + + + + + + + + Search algorithms — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Search algorithms

+

ODAT-SE searches the parameter space \(\mathbf{X}\ni x\) by using the search algorithm Algorithm and the result of Solver \(f(x)\). +In this section, the search algorithms implemented in ODAT-SE are described.

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/algorithm/mapper_mpi.html b/manual/v3.0.0/en/algorithm/mapper_mpi.html new file mode 100644 index 00000000..467d7f4b --- /dev/null +++ b/manual/v3.0.0/en/algorithm/mapper_mpi.html @@ -0,0 +1,166 @@ + + + + + + + + Direct parallel search mapper — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Direct parallel search mapper

+

mapper_mpi is an algorithm to search for the minimum value by computing \(f(x)\) on all the candidate points in the parameter space prepared in advance. +In the case of MPI execution, the set of candidate points is divided into equal parts and automatically assigned to each process to perform trivial parallel computation.

+
+

Preparation

+

For MPI parallelism, you need to install mpi4py.

+
$ python3 -m pip install mpi4py
+
+
+
+
+

Input parameters

+
+

[param] section

+

In this section, the search parameter space is defined.

+

If mesh_path is defined, it is read from a mesh file. +In the mesh file, one line defines one point in the parameter space, the first column is the data number, and the second and subsequent columns are the coordinates of each dimension.

+

If mesh_path is not defined, min_list, max_list, and num_list are used to create an evenly spaced grid for each parameter.

+
    +

  • mesh_path

    +

    Format: String

    +

    Description: Path to the mesh definition file.

    +
    • +

  • min_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: The minimum value the parameter can take.

    +
    • +

  • max_list

    +

    Format: List of float.The length should match the value of dimension.

    +

    Description: The maximum value the parameter can take.

    +
    • +

  • num_list

    +

    Format: List of integer. The length should match the value of dimension.

    +

    Description: The number of grids the parametar can take at each dimension.

    +
    • +
+
+
+
+

Refernce file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +1 + dimension columns are required. +The first column is the index of the mesh, and the second and subsequent columns are the values of parameter. +The lines starting from # are ignored as comments.

+

A sample file for two dimensions is shown below.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

Output file

+
+

ColorMap.txt

+

This file contains the candidate parameters for each mesh and the function value at that time. +The mesh data is listed in the order of the variables defined in string_list in the [solver] - [param] sections of the input file, and the value of the function value is listed last.

+

Below, output example is shown.

+
6.000000 6.000000 0.047852
+6.000000 5.750000 0.055011
+6.000000 5.500000 0.053190
+6.000000 5.250000 0.038905
+6.000000 5.000000 0.047674
+6.000000 4.750000 0.065919
+6.000000 4.500000 0.053675
+6.000000 4.250000 0.061261
+6.000000 4.000000 0.069351
+6.000000 3.750000 0.071868
+...
+
+
+
+
+
+

Restart

+

The execution mode is specified by the run_mode parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to --init, --resume, and --cont options of odatse command, respectively.

+
    +

  • "initial" (default)

    +

    The program is started from the initial state. +If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions:

    +
      +

    1. the specified number of grid points has been evaluated, or the specified period of time has passed.

      2. +

    2. at the end of the execution.

      3. +
    +
    • +

  • "resume"

    +

    The program execution is resumed from the latest checkpoint. +The conditions such as the number of MPI processes should be kept the same.

    +
    • +

  • "continue"

    +

    The continue mode is not supported.

    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/algorithm/minsearch.html b/manual/v3.0.0/en/algorithm/minsearch.html new file mode 100644 index 00000000..c36437d2 --- /dev/null +++ b/manual/v3.0.0/en/algorithm/minsearch.html @@ -0,0 +1,173 @@ + + + + + + + + Nelder-Mead method minsearch — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Nelder-Mead method minsearch

+

When minsearch is selcted, the optimization by the Nelder-Mead method (a.k.a. downhill simplex method) will be done. In the Nelder-Mead method, assuming the dimension of the parameter space is \(D\), the optimal solution is searched by systematically moving pairs of \(D+1\) coordinate points according to the value of the objective function at each point.

+

An important hyperparameter is the initial value of the coordinates. +Although it is more stable than the simple steepest descent method, it still has the problem of being trapped in the local optimum solution, so it is recommended to repeat the calculation with different initial values several times to check the results.

+

In ODAT-SE, the Scipy’s function scipy.optimize.minimize(method="Nelder-Mead") is used. +For details, see the official document .

+
+

Preparation

+

You will need to install scipy .

+
$ python3 -m pip install scipy
+
+
+
+
+

Input parameters

+

It has subsections param and minimize.

+
+

[param] section

+
    +

  • initial_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: Initial value of the parameter. If not defined, it will be initialized uniformly and randomly.

    +
    • +

  • unit_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: +Units for each parameter. +In the search algorithm, each parameter is divided by each of these values to perform a simple dimensionless and normalization. +If not defined, the value is 1.0 for all dimensions.

    +
    • +

  • min_list

    +

    Format: List of float. Length should be equal to dimension.

    +

    Description: +Minimum value of each parameter. +When a parameter falls below this value during the Nelson-Mead method, +the solver is not evaluated and the value is considered infinite.

    +
    • +

  • max_list

    +

    Format: List of float. Length should be equal to dimension.

    +

    Description: +Maximum value of each parameter. +When a parameter exceeds this value during the Nelson-Mead method, +the solver is not evaluated and the value is considered infinite.

    +
    • +
+
+
+

[minimize] section

+

Set the hyperparameters for the Nelder-Mead method. +See the documentation of scipy.optimize.minimize for details.

+
    +

  • initial_scale_list

    +

    Format: List of float. The length should match the value of dimension.

    +

    Description: +The difference value that is shifted from the initial value in order to create the initial simplex for the Nelder-Mead method. +The initial_simplex is given by the sum of initial_list and the dimension of the initial_list plus one component of the initial_scale_list. +If not defined, scales at each dimension are set to 0.25.

    +
    • +

  • xatol

    +

    Format: Float (default: 1e-4)

    +

    Description: Parameters used to determine convergence of the Nelder-Mead method.

    +
    • +

  • fatol

    +

    Format: Float (default: 1e-4)

    +

    Description: Parameters used to determine convergence of the Nelder-Mead method.

    +
    • +

  • maxiter

    +

    Format: Integer (default: 10000)

    +

    Description: Maximum number of iterations for the Nelder-Mead method.

    +
    • +

  • maxfev

    +

    Format: Integer (default: 100000)

    +

    Description: Maximum number of times to evaluate the objective function.

    +
    • +
+
+
+
+

Output files

+
+

SimplexData.txt

+

Outputs information about the process of finding the minimum value. +The first line is a header, the second and subsequent lines are step, +the values of variables defined in string_list in the [solver] - [param] sections of the input file, +and finally the value of the function.

+

The following is an example of the output.

+
#step z1 z2 z3 R-factor
+0 5.25 4.25 3.5 0.015199251773721183
+1 5.25 4.25 3.5 0.015199251773721183
+2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375
+3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261
+4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+
+
+
+
+

res.txt

+

The value of the final objective function and the value of the parameters at that time are described. +The objective function is listed first, followed by the values of the variables defined in string_list in the [solver] - [param] sections of the input file, in that order.

+

The following is an example of the output.

+
fx = 7.382680568652868e-06
+z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+
+
+
+

Restart

+

The restarting is not supported for the optimization by the Nelder-Mead method.

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/algorithm/pamc.html b/manual/v3.0.0/en/algorithm/pamc.html new file mode 100644 index 00000000..37cd939f --- /dev/null +++ b/manual/v3.0.0/en/algorithm/pamc.html @@ -0,0 +1,453 @@ + + + + + + + + Population Annealing Monte Carlo pamc — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Population Annealing Monte Carlo pamc

+

pamc explores the parameter space by using the Population Annealing Monte Carlo (PAMC) method.

+
+

Preparation

+

mpi4py should be installed for the MPI parallelization.

+
$ python3 -m pip install mpi4py
+
+
+
+
+

Input parameters

+

This has two subsections algorithm.param and algorithm.pamc .

+
+

[algorithm.param]

+

This defines a space to be explored. +When mesh_path key is defined the discrete space is used. +Otherwise, continuous space is used.

+
    +

  • Continuous space

    +
      +

    • initial_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +Initial value of parameters. +If not defined, these will be initialize randomly.

      +
      • +

    • min_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +Minimum value of each parameter. +When a parameter falls below this value during the Monte Carlo search, +the solver is not evaluated and the value is considered infinite.

      +
      • +

    • max_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +Maximum value of each parameter. +When a parameter exceeds this value during the Monte Carlo search, +the solver is not evaluated and the value is considered infinite.

      +
      • +

    • step_list

      +

      Format: List of float. Length should be equal to dimension.

      +

      Description: +The step length in one Monte Carlo update (deviation of Gaussian distribution).

      +
      • +
    +
    • +

  • Discrete space

    +
      +

    • mesh_path

      +

      Format: string

      +

      Description: Path to the mesh definition file.

      +
      • +

    • neighborlist_path

      +

      Format: string

      +

      Description: Path to the neighborhood-list file.

      +
      • +
    +
    • +
+
+
+

[algorithm.pamc]

+
    +

  • numsteps

    +

    Format: Integer

    +

    Description: The number of Monte Carlo steps.

    +
    • +

  • numsteps_annealing

    +

    Format: Integer

    +

    Description: The number of interval Monte Carlo steps between lowering “temperature”.

    +
    • +

  • Tnum

    +

    Format: Integer

    +

    Description: The number of “temperature” points.

    +
    • +

  • Tmin

    +

    Format: Float

    +

    Description: The minimum value of the “temperature” (\(T\)).

    +
    • +

  • Tmax

    +

    Format: Float

    +

    Description: The maximum value of the “temperature” (\(T\)).

    +
    • +

  • bmin

    +

    Format: Float

    +

    Description: The minimum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • bmax

    +

    Format: Float

    +

    Description: The maximum value of the “inverse temperature” (\(\beta = 1/T\)). +One of the “temperature” and “inverse temperature” should be defined.

    +
    • +

  • Tlogspace

    +

    Format: Boolean (default: true)

    +

    Description: Whether to assign “temperature” to replicas equally spaced in the logarithmic space or not.

    +
    • +

  • nreplica_per_proc

    +

    Format: Integer (default: 1)

    +

    Description: The number of replicas in a MPI process.

    +
    • +

  • resampling_interval

    +

    Format: Integer (default: 1)

    +

    Description: The number of annealing processes between resampling of the replicas.

    +
    • +

  • fix_num_replicas

    +

    Format: Boolean (default: true)

    +

    Description: Whether to fix the number of replicas or not on resampling.

    +
    • +
+
+

About the number of steps

+

Specify just two of numstep, numsteps_annealing, and numT. +The value of the remaining one will be determined automatically.

+
+
+
+
+

Reference file

+
+

Mesh definition file

+

Define the grid space to be explored in this file. +The first column is the index of the mesh, and the second and subsequent columns are the values of variables. +Note that the index of the mesh will be ignored for this “algorithm”.

+

Below, a sample file is shown.

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

Neighborhood-list file

+

Before searching in the discrete space by Markov Chain Monte Carlo method, +we should define “neighborhoods” for each point \(i\), which are points that a walker can move from \(i\) +A neighborhood-list file defines the list of neighborhoods. +In this file, the index of an initial point \(i\) is specified by the first column, +and the indices of final points \(j\) are specified by the second and successive columns.

+

An utility tool, odatse_neighborlist is available for generating a neighborhood-list file from a mesh file. For details, please see Related Tools.

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

Output files

+
+

RANK/trial_T#.txt

+

This file stores the suggested parameters and the corresponding value returned from the solver for each temperature point (specified by #). +The first column (step) is the index of the MC step. +The second column (walker) is the index of the walker in the process. +The third column (beta) is the inverse temperature of the replica. +The fourth column (fx) is the value of the solver. +The fifth - (4+dimension)-th columns are the coordinates. +The last two columns (weight and ancestor) are the Neal-Jarzynsky weight and the grand-ancestor of the replica.

+

Example:

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/trial.txt

+

This is a combination of all the trial_T#.txt in one.

+
+
+

RANK/result_T#.txt

+

This file stores the sampled parameters and the corresponding value returned from the solver for each replica and each temperature. +This has the same format as trial.txt.

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/result.txt

+

This is a combination of all the result_T#.txt in one.

+
+
+

best_result.txt

+

The optimal value of the solver and the corresponding parameter among the all samples.

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

fx.txt

+

This file stores statistical metrics over the all replicas for each temperature. +The first column is inverse temperature. +The second and third column are the expectation value and the standard error of the solver’s output (\(f(x)\)), respectively. +The fourth column is the number of replicas. +The fifth column is the logarithmic of the ratio between the normalization factors (partition functions)

+
+\[\log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)},\]
+

where \(\beta_0\) is the minimum value of \(\beta\) used in the calculation. +The sixth column is the acceptance ratio of MC updates.

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804
+0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058
+0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004
+...
+
+
+
+
+
+

Restart

+

The execution mode is specified by the run_mode parameter to the constructor. +The operation of each mode is described as follows. +The parameter values correspond to --init, --resume, and --cont options of odatse command, respectively.

+
    +

  • "initial" (default)

    +

    The program is started from the initialized state. +If the checkpointing is enabled, the intermediate states will be stored at the folloing occasions:

    +
      +

    1. at the end of calculation at each temperature point, the specified number of steps has been done, or the specified period of time has passed.

      2. +

    2. at the end of the execution.

      3. +
    +
    • +

  • "resume"

    +

    The program execution is resumed from the latest checkpoint. +The conditions such as the number of MPI processes should be kept the same.

    +
    • +

  • "continue"

    +

    The program execution is continued from the previous run. +The sequence of the temperature points should be specified so that it is continuous from that of the previous run.

    +

    Assume that the temperature has been lowered from Tmax= \(T^{(1)}\) to Tmin= \(T^{(2)}\) in the previous run, the next values should be taken as Tmax= \(T^{(2)}\) and Tmin= \(T^{(3)}\). +In the new calculation, the temperature points are taken from \(T^{(2)}\) to \(T^{(3)}\) divided by Tnum, namely, \(T_0 = T^{(2)}\), \(T_1\),…, \(T_{\text{Tnum}-1}=T^{(3)}\). (Tnum can be different from the previous run.)

    +
    • +
+
+
+

Algorithm

+
+

Goal

+

When the weight of the configuration \(x\) under some parameter \(\beta_i\) is given as \(f_i(x)\) +(e.g., the Bolzmann factor \(f_i(x) = \exp[-\beta_i E(x)]\) ), +the expectation value of \(A\) is defined as

+
+\[\langle A\rangle_i += \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} += \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) += \int \mathrm{d}xA(x)\tilde{f}_i(x),\]
+

where \(Z = \int \mathrm{d} x f_i(x)\) is the normalization factor (partition function) +and \(\tilde{f}(x) = f(x)/Z\) is the probability of \(x\).

+

Our goal is to numerically calculate the expectation value for each \(\beta_i\) and the (ratio of) the normalization factor.

+
+
+

Annealed Importance Sampling (AIS) [1]

+

First, we introduce a series of configurations \(\{x_i\}\) obeying the following joint probability

+
+\[\tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0),\]
+

with

+
+\[\tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)},\]
+

where \(T_i(x, x')\) is a transition probability from \(x\) to \(x'\) under \(\beta_i\) +holding the balance condition,

+
+\[\int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x').\]
+

It turns out that \(\tilde{f}_n(x_n)\) is the marginal distribution of \(\tilde{f}(x_0, x_1, \dots, x_n)\), that is,

+
+\[\tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n),\]
+

from

+
+\[\int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) += \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) += 1.\]
+

Consequently, +\(\langle A \rangle_n\) is represented by using the extended configuration \(\{x_i\}\) as

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&\equiv +\int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n). +\end{split}\end{split}\]
+

Unfortunately, it is difficult to generate directly a series of configurations \(\{x_i\}\) +following the distribution \(\tilde{f}(x_0, x_1, \dots, x_n)\). +Then, instead of \(\tilde{f}(x_0, x_1, \dots, x_n)\), we consider \(\{x_i\}\) obeying the joint distribution

+
+\[\tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n),\]
+

by using the following the following scheme:

+
    +

  1. Generete \(x_0\) from the initial distribution \(\tilde{f}_0(x)\)

    2. +

  2. Generate \(x_{i+1}\) from \(x_i\) through \(T_{i+1}(x_i, x_{i+1})\)

    3. +
+

By using the reweighting method (or importance sampling method), +\(\langle A \rangle_n\) is rewritten as

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ +&= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} +\end{split}.\end{split}\]
+

Because the ratio between \(\tilde{f}\) and \(\tilde{g}\) is

+
+\[\begin{split}\begin{split} +\frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\frac{f_n(x_n)}{f_0(x_0)} +\prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ +&\equiv +\frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n), +\end{split}\end{split}\]
+

the form of the expectation value will be

+
+\[\langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} += \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n}.\]
+

Finally, the ratio between the normalization factors \(Z_n/Z_0\) can be evaluated as

+
+\[\frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n},\]
+

and therefore the expectation value of \(A\) can be evaluated as a weighted arithmetic mean:

+
+\[\langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}}.\]
+

This weight \(w_n\) is called as the Neal-Jarzynski weight.

+
+
+

population annealing (PA) [2]

+

Although the AIS method can estimate the expectation values of \(A\) for each parameter \(\beta\) as the form of weighted arithmetic mean, +the variance of weights \(w\) is generally large and then the accuracy of the result gets worse. +In order to overcome this problem, the population annealing Monte Carlo (PAMC) method resamples all the replicas according to the probability +\(p^{(k)} = w^{(k)} / \sum_k w^{(k)}\) at some periods and resets all the weights to unity.

+

The following pseudo code describes the scheme of PAMC:

+
for k in range(K):
+    w[0, k] = 1.0
+    x[0, k] = draw_from(β[0])
+for i in range(1, N):
+    for k in range(K):
+        w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) )
+    if i % interval == 0:
+        x[i, :] = resample(x[i, :], w[i, :])
+        w[i, :] = 1.0
+    for k in range(K):
+        x[i, k] = transfer(x[i-1, k], β[i])
+    a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:])
+
+
+

There are two resampling methods: one with a fixed number of replicas[2] and one without[3].

+
+
+

References

+

[1] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[2] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[3] J. Machta, Phys. Rev. E 82, 026704 (2010).

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/contact.html b/manual/v3.0.0/en/contact.html new file mode 100644 index 00000000..4b646a94 --- /dev/null +++ b/manual/v3.0.0/en/contact.html @@ -0,0 +1,71 @@ + + + + + + + + Contact — ODAT-SE 3.0-dev documentation + + + + + + + + + + + +
+ + +
+

Contact

+
    +

  • Bug Reports

    +

    Please report all problems and bugs on the github Issues page.

    +

    To resolve bugs early, follow these guidelines when reporting:

    +
      +

    1. Please specify the version of ODAT-SE you are using.

      2. +

    2. If there are problems for installation, please inform us about your operating system and the compiler.

      3. +

    3. If a problem occurs during execution, enter the input file used for execution and its output.

      4. +
    +

    Thank you for your cooperation.

    +
    • +

  • Others

    +

    If you have any questions about your research that are difficult to consult at Issues on GitHub, please send an e-mail to the following address:

    +

    E-mail: 2dmat-dev__at__issp.u-tokyo.ac.jp (replace _at_ by @)

    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/customize/algorithm.html b/manual/v3.0.0/en/customize/algorithm.html new file mode 100644 index 00000000..3e04570b --- /dev/null +++ b/manual/v3.0.0/en/customize/algorithm.html @@ -0,0 +1,268 @@ + + + + + + + + Algorithm — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Algorithm

+

Algorithm is defined as a subclass of odatse.algorithm.AlgorithmBase:

+
import odatse
+
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    pass
+
+
+
+

AlgorithmBase

+

AlgorithmBase class offers the following methods.

+
    +

  • __init__(self, info: odatse.Info, runner: odatse.Runner = None)

    +
      +

    • Reads the common parameters from info and sets the following instance variables:

      +
        +

      • self.mpicomm: Optional[MPI.Comm] : MPI.COMM_WORLD

        • +

      • self.mpisize: int : the number of MPI processes

        • +

      • self.mpirank: int : the rank of this process

        +
          +

        • When import mpi4py fails, self.mpicomm is set to None, self.mpisize is set to 1, and self.mpirank is set to 0.

          • +
        +
        • +

      • self.rng: np.random.Generator : pseudo random number generator

        + +
        • +

      • self.dimension: int : the dimension of the parameter space

        • +

      • self.label_list: List[str] : the name of each axes of the parameter space

        • +

      • self.root_dir: pathlib.Path : root directory

        +
          +

        • It is taken from info.base["root_dir"].

          • +
        +
        • +

      • self.output_dir: pathlib.Path : output directory

        +
          +

        • It is taken from info.base["output_dir"].

          • +
        +
        • +

      • self.proc_dir: pathlib.Path : working directory of each process

        +
          +

        • It is set to self.output_dir / str(self.mpirank).

          • +

        • The directory will be made automatically.

          • +

        • Each process performs an optimization algorithm in this directory.

          • +
        +
        • +

      • self.timer: dict[str, dict] : dictionary storing elapsed time

        +
          +

        • Three empty dictinaries, "prepare", "run", and "post", will be defined.

          • +
        +
        • +

      • self.checkpoint: bool : enable/disable checkpointing

        +
          +

        • self.checkpoint_steps

          • +

        • self.checkpoint_interval

          • +

        • self.checkpoint_file

          +

          The parameters concerning the checkpointing feature are stored.

          +
          • +
        +
        • +
      +
      • +
    +
    • +

  • prepare(self) -> None

    +
    +
      +

    • Prepares the algorithm.

      • +

    • It should be called before self.run() is called.

      • +
    +
    +
    • +

  • run(self) -> None

    +
    +
      +

    • Performs the algorithm

      • +

    • The following steps are executed:

      +
        +

      1. Enter into the directory self.proc_dir.

        2. +

      2. Run self.runner.prepare().

        3. +

      3. Run self._run().

        4. +

      4. Run self.runner.post().

        5. +

      5. Move to the original directory.

        6. +
      +
      • +

    • It should be called after self.prepare() is called.

      • +
    +
    +
    • +

  • post(self) -> Dict

    +
    +
      +

    • Runs a post process of the algorithm, for example, writing the results into files.

      • +

    • Enters into self.output_dir, calls self._post(), and returns to the original directory.

      • +

    • It should be called after self.run() is called.

      • +
    +
    +
    • +

  • main(self, run_mode) -> Dict

    +
    +
      +

    • Calls prepare, run, and post.

      • +

    • Measures the elapsed times for calling functions, and writes them into a file

      • +

    • Takes an argument for the execution mode as a string. The default value is initialize.

      +
        +

      • "initialize": start from the initial state.

        • +

      • "resume": resume from the interrupted run.

        • +

      • "continue": continue from the finished run.

        • +
      +

      The argument contains "-resetrand" when the random number generator should be initialized. +The behavior of “continue” depends on the algorithm.

      +
      • +

    • Returns the result of the optimization in the form of dictionary.

      • +
    +
    +
    • +
+
+
+

Algorithm

+

Algorithm provides a concrete description of the algorithm. +It is defined as a subclass of AlgorithmBase and should have the following methods.

+
    +

  • __init__(self, info: odatse.Info, runner: odatse.Runner = None, domain = None)

    +
    +
      +

    • The arguments info and runner should be transferred to the constructor of the base class:

      +
      +
        +

      • super().__init__(info=info, runner=runner)

        • +
      +
      +
      • +

    • Reads info and sets information.

      • +

    • If domain is given, the search region should be taken from the domain parameter. +Otherwise, the search region should be created from info by odatse.domain.Region(info) (for continuous parameter space) or odatse.domain.MeshGrid(info) (for discrete parameter space).

      • +
    +
    +
    • +

  • _prepare(self) -> None

    +
    +
      +

    • Describes pre-processes of the algorithm.

      • +
    +
    +
    • +

  • _run(self) -> None

    +
    +
      +

    • Describes the algorithm body.

      • +

    • In order to obtain the value of the objective function f(x) for the search parameter x, the method of Runner class should be called in the following manner:

      +
      args = (step, set)
+fx = self.runner.submit(x, args)
+
      +
      +
      • +
    +
    +
    • +

  • _post(self) -> Dict

    +
    +
      +

    • Describes post-process of the algorithm.

      • +

    • Returns the result of the optimization in the form of dictionary.

      • +
    +
    +
    • +
+
+
+

Definition of Domain

+

Two classes are preprared to specify the search region.

+
+

Region class

+

Region is a helper class to define a continuous parameter space.

+
    +

  • The constructor takes an Info object, or a dictionary in param= form.

    +
      +

    • When the Info object is given, the lower and upper bounds of the region, the units, and the initial values are obtained from Info.algorithm.param field.

      • +

    • When the dictionary is given, the corresponding data are taken from the dictionary data.

      • +

    • For details, see [algorithm.param] subsection for minsearch

      • +
    +
    • +

  • Initialize(self, rnd, limitation, num_walkers) should be called to set the initial values. +The arguments are the random number generator rng, the constraint object limitation, and the number of walkers num_walkers.

    • +
+
+
+

MeshGrid class

+

MeshGrid is a helper class to define a discrete parameter space.

+
    +

  • The constructor takes an Info object, or a dictionary in param= form.

    +
      +

    • When the Info object is given, the lower and upper bounds of the region, the units, and the initial values are obtained from Info.algorithm.param field.

      • +

    • When the dictionary is given, the corresponding data are taken from the dictionary data.

      • +

    • For details, see [algorithm.param] subsection for mapper

      • +
    +
    • +

  • do_split(self) should be called to divide the grid points and distribute them to MPI ranks.

    • +

  • For input and output, the following methods are provided.

    +
      +

    • A class method from_file(cls, path) is prepared that reads mesh data from path and creates an instance of MeshGrid class.

      • +

    • A method store_file(self, path) is prepared that writes the grid information to the file specified by path.

      • +
    +
    • +
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/customize/common.html b/manual/v3.0.0/en/customize/common.html new file mode 100644 index 00000000..0a4640a5 --- /dev/null +++ b/manual/v3.0.0/en/customize/common.html @@ -0,0 +1,171 @@ + + + + + + + + Commons — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Commons

+

In this section, the components commonly used over the program are described.

+
+

odatse.Info

+

This class treats the input parameters. +It contains the following four instance variables.

+
    +

  • base : dict[str, Any]

    +
      +

    • Parameters for whole program such as the directory where the output will be written.

      • +
    +
    • +

  • solver : dict[str, Any]

    +
      +

    • Parameters for Solver

      • +
    +
    • +

  • algorithm : dict[str, Any]

    +
      +

    • Parameters for Algorithm

      • +
    +
    • +

  • runner : dict[str, Any]

    +
      +

    • Parameters for Runner

      • +
    +
    • +
+

An instance of Info is initialized by passing a dict which has the following four sub dictionaries, base, solver, algorithm, and runner. (Some of them can be omitted.) +Each sub dictionary is set to the corresponding field of Info. +Alternatively, it can be created by passing to the class method from_file a path to input file in TOML format.

+
+

base items

+

As items of base field, root_dir indicating the root dirctory of the calculation, and output_dir for output results will be set automatically as follows.

+
    +

  • Root directory root_dir

    +
      +

    • The default value is "." (the current directory).

      • +

    • The value of root_dir will be converted to an absolute path.

      • +

    • The leading ~ will be expanded to the user’s home directory.

      • +

    • Specifically, the following code is executed:

      +
      p = pathlib.Path(base.get("root_dir", "."))
+base["root_dir"] = p.expanduser().absolute()
+
      +
      +
      • +
    +
    • +

  • Output directory output_dir

    +
      +

    • The leading ~ will be expanded to the user’s home directory.

      • +

    • If an absolute path is given, it is set as-is.

      • +

    • If a relative path is given, it is regarded to be relative to root_dir.

      • +

    • The default value is ".", that is, the same to root_dir

      • +

    • Specifically, the following code is executed:

      +
      p = pathlib.Path(base.get("work_dir", "."))
+p = p.expanduser()
+base["work_dir"] = base["root_dir"] / p
+
      +
      +
      • +
    +
    • +
+
+
+
+

odatse.Runner

+

Runner is a class that connects Algorithm and Solver. +The constructor of Runner takes instances of Solver, Info, Mapping, and Limitation. +If the instance of Mapping is omitted, TrivialMapping is assumed that does no transformation. +If the instance of Limitation is omitted, Unlimited is assumed that do not impose constraints.

+

submit(self, x: np.ndarray, args: Tuple[int,int]) -> float method invokes the solver and returns the value of objective function f(x). +submit internally uses the instance of Limitation to check whether the search parameter x satisfies the constraints. Then, it applies the instance of Mapping to obtain from x the input y = mapping(x) that is actually used by the solver.

+

See Input file for details how/which components of info Runner uses.

+
+
+

odatse.Mapping

+

Mapping is a class that describes mappings from the search parameters of the inverse problem analysis algorithms to the variables of the direct problem solvers. +It is defined as a function object class that has __call__(self, x: np.ndarray) -> np.ndarray method. +In the current version, a trivial transformation TrivialMapping and an affine mapping Affine are defined.

+
+

TrivialMapping

+

TrivialMapping provides a trivial transformation \(x\to x\), that is, no transformation. +It is taken as a default to the argument of Runner class.

+
+
+

Affine

+

Affine provides an affine mapping \(x \to y = A x + b\). +The coefficients A and b should be given as constructor arguments, or passed as dictionary elements through the from_dict class method. +In case when they are specified in the input file of ODAT-SE, the format of the parameter may be referred to the input file section of the manual.

+
+
+
+

odatse.Limitation

+

Limitation is a class that describes constraints on the \(N\) dimensional parameter space \(x\) searched by the inverse problem analysis algorithms. +It is defined as a class that have the method judge(self, x: np.ndarray) -> bool. +In the current version, Unlimited class that imposes no constraint, and Inequality class that represents the linear inequality constraint.

+
+

Unlimited

+

Unlimited represents that no constraint is imposed. +judge method always returns True. +It is taken as a default to the argument of Runner class.

+
+
+

Inequality

+

Inequality is a class that expresses \(M\) constraints imposed on \(N\) dimensional search parameters \(x\) in the form \(A x + b > 0\) where \(A\) is a \(M \times N\) matrix and \(b\) is a \(M\) dimensional vector.

+

The coefficients A and b should be given as constructor arguments, or passed as dictionary elements through the from_dict class method. +In case when they are specified in the input file of ODAT-SE, the format of the parameter may be referred to the input file section of the manual.

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/customize/index.html b/manual/v3.0.0/en/customize/index.html new file mode 100644 index 00000000..55c34195 --- /dev/null +++ b/manual/v3.0.0/en/customize/index.html @@ -0,0 +1,72 @@ + + + + + + + + (For developers) User-defined algorithms and solvers — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

(For developers) User-defined algorithms and solvers

+

ODAT-SE solves the inverse problems by the combination of Solver for the direct problems and Algorithm for the optimization methods. +Instead of using Solver and Algorithm provided by ODAT-SE, users can define and use their own components. +In this chapter, how to define Solver and Algorithm and to use them will be described.

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/customize/solver.html b/manual/v3.0.0/en/customize/solver.html new file mode 100644 index 00000000..1da24c04 --- /dev/null +++ b/manual/v3.0.0/en/customize/solver.html @@ -0,0 +1,117 @@ + + + + + + + + Solver — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Solver

+

Solver is a class that describes the direct problem, providing a method evaluate that returns the value of the objective function from the input parameters.

+
    +

  • Solver is define as a derived class of odatse.solver.SolverBase.

    +
    import odatse
+
+class Solver(odatse.solver.SolverBase):
+    pass
+
    +
    +
    • +

  • Constructor

    +

    Solver class should have a constructor that takes an Info class object as an argument:

    +
    def __init__(self, info: odatse.Info):
+    super().__init__(info)
+
    +
    +

    It is required to call the constructor of the base class with the info object. +There the following instance variables are introduced:

    +
      +

    • self.root_dir: pathlib.Path : Root directory

      +

      This parameter is taken from info.base["root_dir"], and represents the directory in which odatse is executed. It can be referred as a root location when the external programs or data files are read.

      +
      • +

    • self.output_dir: pathlib.Path : Output directory

      +

      This parameter is taken from info.base["output_dir"], and used for the directory in which the result files are written. Usually, when the MPI parallelization is applied, the accumulated results are stored.

      +
      • +

    • self.proc_dir: pathlib.Path : Working directory for each MPI process by the form self.output_dir / str(mpirank)

      +

      The evaluate method of Solver is called from Runner with the proc_dir directory set as the current directory, in which the intermediate results produced by each rank are stored. When the MPI parallelization is not used, the rank number is treated as 0.

      +
      • +
    +

    The parameters for the Solver class can be obtained from solver field of info object. +The required parameters should be taken and stored.

    +
    • +

  • evaluate method

    +

    The form of evaluate method should be as follows:

    +
    def evaluate(self, x, args=(), nprocs=1, nthreads=1) -> float:
+    pass
+
    +
    +

    This method evaluates the objective function at a given parameter value x and returns the result. It takes the following arguments:

    +
      +

    • x: np.ndarray

      +

      The parameter value in \(N\) dimensional vector of numpy.ndarray type.

      +
      • +

    • args: Tuple = ()

      +

      The additional arguments passed from the Algorithm in the form of a Tuple of two integers. +One is the step count that corresponds to the Monte Carlo steps for MC type algorithms, or the index of the grid point for grid search algorithm. +The other is the set number that represents \(n\)-th iteration.

      +
      • +

    • nprocs: int = 1

      • +

    • nthreads: int = 1

      +

      The number of processes and threads that specify how to run the solver in MPI/thread parallelisation. In the current version, nprocs=1 and nthreads=1 are accepted.

      +
      • +
    +

    The evaluate method returns the value of the objective function as a float number.

    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/customize/usage.html b/manual/v3.0.0/en/customize/usage.html new file mode 100644 index 00000000..624ee9ce --- /dev/null +++ b/manual/v3.0.0/en/customize/usage.html @@ -0,0 +1,104 @@ + + + + + + + + Usage — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Usage

+

The following flow solves the optimization problem. +The number of flow corresponds the comment in the program example.

+
    +

  1. Define your Algorithm and/or Solver.

    +
      +

    • Classes that ODAT-SE provides are available, of course.

      • +
    +
    2. +

  2. Prepare the input parameter, info: odatse.Info.

    +
      +

    • Info class has a class method to read input files in TOML format. +It is also possible to prepare a set of parameters as a dict and to pass it to the constructor of Info class.

      • +
    +
    3. +

  3. Instantiate solver: Solver, runner: odatse.Runner, and algorithm: Algorithm.

    4. +

  4. Invoke algorithm.main().

    5. +
+

Example:

+
import sys
+import odatse
+
+# (1)
+class Solver(odatse.solver.SolverBase):
+    # Define your solver
+    ...
+
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    # Define your algorithm
+    ...
+
+
+# (2)
+input_file = sys.argv[1]
+info = odatse.Info.from_file(input_file)
+
+# (3)
+solver = Solver(info)
+runner = odatse.Runner(solver, info)
+algorithm = Algorithm(info, runner)
+
+# (4)
+result = algorithm.main()
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/genindex.html b/manual/v3.0.0/en/genindex.html new file mode 100644 index 00000000..288665ad --- /dev/null +++ b/manual/v3.0.0/en/genindex.html @@ -0,0 +1,52 @@ + + + + + + + Index — ODAT-SE 3.0-dev documentation + + + + + + + + + + +
+ + + +

Index

+ +
+ +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/index.html b/manual/v3.0.0/en/index.html new file mode 100644 index 00000000..71b21b30 --- /dev/null +++ b/manual/v3.0.0/en/index.html @@ -0,0 +1,122 @@ + + + + + + + + Welcome to ODAT-SE documentation! — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Welcome to ODAT-SE documentation!

+
+

Contents:

+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/input.html b/manual/v3.0.0/en/input.html new file mode 100644 index 00000000..8114abc4 --- /dev/null +++ b/manual/v3.0.0/en/input.html @@ -0,0 +1,290 @@ + + + + + + + + Input file — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Input file

+

As the input file format, TOML format is used. +The input file consists of the following four sections.

+
    +

  • base

    +
      +

    • Specify the basic parameters about ODAT-SE.

      • +
    +
    • +

  • solver

    +
      +

    • Specify the parameters about Solver .

      • +
    +
    • +

  • algorithm

    +
      +

    • Specify the parameters about Algorithm .

      • +
    +
    • +

  • runner

    +
      +

    • Specify the parameters about Runner .

      • +
    +
    • +
+
+

[base] section

+
    +

  • dimension

    +

    Format: Integer

    +

    Description: Dimension of the search space (number of parameters to search)

    +
    • +

  • root_dir

    +

    Format: string (default: The directory where the program was executed)

    +

    Description: Name of the root directory. The origin of the relative paths to input files.

    +
    • +

  • output_dir

    +

    Format: string (default: The directory where the program was executed)

    +

    Description: Name of the directory to output the results.

    +
    • +
+
+
+

[solver] section

+

The name determines the type of solver. Each parameter is defined for each solver.

+
    +

  • name

    +

    Format: String

    +

    Description: Name of the solver. The following solvers are available.

    +
    +
      +

    • analytical : Solver to provide analytical solutions (mainly used for testing).

      • +

    • sim-trhepd-rheed : +Solver to calculate Total-reflection high energy positron diffraction (TRHEPD) or Reflection High Energy Electron Diffraction (RHEED) intensities.

      • +

    • sxrd : Solver for Surface X-ray Diffraction (SXRD)

      • +

    • leed : Solver for Low-energy Electron Diffraction (LEED)

      • +
    +
    +
    • +

  • dimension

    +

    Format: Integer (default: base.dimension)

    +

    Description: +Number of input parameters for Solvers

    +
    • +
+

See Direct Problem Solver for details of the various solvers and their input/output files.

+
+
+

[algorithm] section

+

The name determines the type of algorithm. Each parameter is defined for each algorithm.

+
    +

  • name

    +

    Format: String

    +

    Description: Algorithm name. The following algorithms are available.

    +
    +
      +

    • minsearch : Minimum value search using Nelder-Mead method

      • +

    • mapper : Grid search

      • +

    • exchange : Replica Exchange Monte Carlo method

      • +

    • pamc : Population Annealing Monte Carlo method

      • +

    • bayes : Bayesian optimization

      • +
    +
    +
    • +

  • seed

    +

    Format: Integer

    +

    Description: +A parameter to specify seeds of the pseudo-random number generator used for random generation of initial values, Monte Carlo updates, etc. +For each MPI process, the value of seed + mpi_rank * seed_delta is given as seeds. +If omitted, the initialization is done by the Numpy’s prescribed method.

    +
    • +

  • seed_delta

    +

    Format: Integer (default: 314159)

    +

    Description: +A parameter to calculate the seed of the pseudo-random number generator for each MPI process. +For details, see the description of seed.

    +
    • +

  • checkpoint

    +

    Format: Boolean (default: false)

    +

    Description: +A parameter to specify whether the intermediate states are periodically stored to files. The final state is also saved. In case when the execution is terminated, it will be resumed from the latest checkpoint.

    +
    • +

  • checkpoint_steps

    +

    Format: Integer (default: 16,777,216)

    +

    Description: +A parameter to specify the iteration steps between the previous and next checkpoints. One iteration step corresponds to one evaluation of grid point in the mapper algorithm, one evaluation of Bayesian search in the bayes algorithm, and one local update in the Monte Carlo (exchange and PAMC) algorithms. +The default value is a sufficiently large number of steps. To enable checkpointing, at least either of checkpoint_steps or checkpoint_interval should be specified.

    +
    • +

  • checkpoint_interval

    +

    Format: Floating point number (default: 31,104,000)

    +

    Description: +A parameter to specify the execution time between the previous and next checkpoints in unit of seconds. +The default value is a sufficiently long period (360 days). To enable checkpointing, at least either of checkpoint_steps or checkpoint_interval should be specified.

    +
    • +

  • checkpoint_file

    +

    Format: String (default: "status.pickle")

    +

    Description: +A parameter to specify the name of output file to which the intermediate state is written. +The files are generated in the output directory of each process. +The past three generations are kept with the suffixes .1, .2, and .3 .

    +
    • +
+

See Search algorithms for details of the various algorithms and their input/output files.

+
+
+

[runner] section

+

This section sets the configuration of Runner, which bridges Algorithm and Solver. +It has three subsections, mapping, limitation, and log .

+
+

[runner.mapping] section

+

This section defines the mapping from an \(N\) dimensional parameter searched by Algorithm, \(x\), to an \(M\) dimensional parameter used in Solver, \(y\) . +In the case of \(N \ne M\), the parameter dimension in [solver] section should be specified.

+

In the current version, the affine mapping (linear mapping + translation) \(y = Ax+b\) is available.

+
    +

  • A

    +

    Format: List of list of float, or a string (default: [])

    +

    Description: +\(N \times M\) matrix \(A\). An empty list [] is a shorthand of an identity matrix. +If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example).

    +
    • +

  • b

    +

    Format: List of float, or a string (default: [])

    +

    Description: +\(M\) dimensional vector \(b\). An empty list [] is a shorthand of a zero vector. +If you want to set it by a string, arrange the elements of the vector separated with spaces.

    +
    • +
+

For example, both

+
A = [[1,1], [0,1]]
+
+
+

and

+
A = """
+1 1
+0 1
+"""
+
+
+

mean

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right).\end{split}\]
+
+
+

[limitation] section

+

This section defines the limitation (constraint) in an \(N\) dimensional parameter searched by Algorithm, \(x\), in addition of min_list and max_list.

+

In the current version, a linear inequation with the form \(Ax+b>0\) is available.

+
    +

  • co_a

    +

    Format: List of list of float, or a string (default: [])

    +

    Description: +\(N \times M\) matrix \(A\). An empty list [] is a shorthand of an identity matrix. +If you want to set it by a string, arrange the elements of the matrix separated with spaces and newlines (see the example).

    +
    • +

  • co_b

    +

    Format: List of float, or a string (default: [])

    +

    Description: +\(M\) dimensional vector \(b\). An empty list [] is a shorthand of a zero vector. +If you want to set it by a string, arrange the elements of the vector separated with spaces.

    +
    • +
+

For example, both

+
A = [[1,1], [0,1]]
+
+
+

and

+
A = """
+1 1
+0 1
+"""
+
+
+

mean

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right).\end{split}\]
+
+
+

[log] section

+

Setting parametrs related to logging of solver calls.

+
    +

  • filename

    +

    Format: String (default: “runner.log”)

    +

    Description: Name of log file.

    +
    • +

  • interval

    +

    Format: Integer (default: 0)

    +

    Description: +The log will be written out every time solver is called interval times. +If the value is less than or equal to 0, no log will be written.

    +
    • +

  • write_result

    +

    Format: Boolean (default: false)

    +

    Description: Whether to record the output from solver.

    +
    • +

  • write_input

    +

    Format: Boolean (default: false)

    +

    Description: Whether to record the input to solver.

    +
    • +
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/introduction.html b/manual/v3.0.0/en/introduction.html new file mode 100644 index 00000000..f153f76f --- /dev/null +++ b/manual/v3.0.0/en/introduction.html @@ -0,0 +1,185 @@ + + + + + + + + Introduction — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Introduction

+
+

What is ODAT-SE ?

+

Open Data Analysis Tool for Science and Engineering (ODAT-SE) is a framework for applying a search algorithm to a direct problem solver to find the optimal solution. +It has been developed by the name 2DMAT, and since version 3, it is organized as an open platform for data analysis by modularizing direct problem solvers and search algorithms.

+

As the standard direct problem solver, the experimental data analysis software for two-dimensional material structure analysis is prepared. The direct problem solver gives the deviation between the experimental data and the calculated data obtained under the given parameters such as atomic positions as a loss function used in the inverse problem. The optimal parameters are estimated by minimizing the loss function using a search algorithm. For further use, the original direct problem solver or the search algorithm can be defined by users. +In the current version, for solving a direct problem, ODAT-SE offers the wrapper of the solver for the total-reflection high-energy positron diffraction (TRHEPD) experiment[1, 2], sxrd[3], and leed[4]. +As algorithms, it offers the Nelder-Mead method[5], the grid search method[6], the Bayesian optimization method[7], the replica exchange Monte Carlo method[8], and the population annealing Monte Carlo method[9-11].

+

In the future, we plan to add other direct problem solvers and search algorithms in ODAT-SE.

+

[1] As a review, see Y. Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019).

+

[2] T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022).

+

[3] W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252, 5259 (2006).

+

[4] M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993).

+

[5] K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020).

+

[6] K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series, 9, 011301 (2023).

+

[7] Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022)

+

[8] K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996), R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986).

+

[9] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[10] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[11] J. Machta, Phys. Rev. E 82, 026704 (2010).

+
+
+

License

+
+
This package is distributed under Mozilla Public License version 2.0 (MPL-2.0).
+
+

Copyright (c) <2020-> The University of Tokyo. All rights reserved.

+

This software was developed with the support of “Project for advancement of software usability in materials science” of The Institute for Solid State Physics, The University of Tokyo. +We hope that you cite the following reference when you publish the results using 2DMAT / ODAT-SE:

+

“Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures”, Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, Computer Physics Communications 280, 108465 (2022).

+

BibTeX:

+
@article{MOTOYAMA2022108465,
+  title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures},
+  journal = {Computer Physics Communications},
+  volume = {280},
+  pages = {108465},
+  year = {2022},
+  issn = {0010-4655},
+  doi = {https://doi.org/10.1016/j.cpc.2022.108465},
+  url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849},
+  author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi}
+}
+
+
+
+
+

Version Information

+
    +

  • ODAT-SE

    +
      +

    • v3.0.0: 2024-11-25

      • +
    +
    • +

  • 2DMAT

    +
      +

    • v2.1.0: 2022-04-08

      • +

    • v2.0.0: 2022-01-17

      • +

    • v1.0.1: 2021-04-15

      • +

    • v1.0.0: 2021-03-12

      • +

    • v0.1.0: 2021-02-08

      • +
    +
    • +
+
+
+

Main developers

+

ODAT-SE has been developed by following members.

+
    +

  • ODAT-SE v3.0.0 -

    +
      +
      • +

      1. Motoyama (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Yoshimi (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Aoyama (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Hoshi (National Institute for Fusion Science)

        2. +
      +
      • +
    +
    • +

  • 2DMAT v2.0.0 -

    +
      +
      • +

      1. Motoyama (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Yoshimi (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Iwamoto (Department of Applied Mathematics and Physics, Tottori University)

        2. +
      +
      • +
      • +

      1. Hoshi (Department of Applied Mathematics and Physics, Tottori University)

        2. +
      +
      • +
    +
    • +

  • 2DMAT v0.1.0 - v1.0.1

    +
      +
      • +

      1. Motoyama (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Yoshimi (The Institute for Solid State Physics, The University of Tokyo)

        2. +
      +
      • +
      • +

      1. Hoshi (Department of Applied Mathematics and Physics, Tottori University)

        2. +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/objects.inv b/manual/v3.0.0/en/objects.inv new file mode 100644 index 00000000..e32a95dc Binary files /dev/null and b/manual/v3.0.0/en/objects.inv differ diff --git a/manual/v3.0.0/en/output.html b/manual/v3.0.0/en/output.html new file mode 100644 index 00000000..b2b299d8 --- /dev/null +++ b/manual/v3.0.0/en/output.html @@ -0,0 +1,112 @@ + + + + + + + + Output files — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Output files

+

See Direct Problem Solver and Search algorithms for the output files of each Solver and Algorithm.

+
+

Common file

+
+

time.log

+

The total time taken for the calculation for each MPI rank is outputted. +These files will be output under the subfolders of each rank respectively. +The time taken to pre-process the calculation, the time taken to compute, and the time taken to post-process the calculation are listed in the prepare , run , and post sections.

+

The following is an example of the output.

+
#prepare
+ total = 0.007259890999989693
+#run
+ total = 1.3493346729999303
+ - file_CM = 0.0009563499997966574
+ - submit = 1.3224223930001244
+#post
+ total = 0.000595873999941432
+
+
+
+
+

runner.log

+

The log information about solver calls for each MPI rank is outputted. +These files will be output under the subfolder of each rank. +The output is only available when the runner.log.interval parameter is a positive integer in the input.

+
    +

  • The first column is the serial number of the solver call.

    • +

  • The second column is the time elapsed since the last solver call.

    • +

  • The third column is the time elapsed since the start of the calculation.

    • +
+

The following is an example of the output.

+
# $1: num_calls
+# $2: elapsed_time_from_last_call
+# $3: elapsed_time_from_start
+
+1 0.0010826379999999691 0.0010826379999999691
+2 6.96760000000185e-05 0.0011523139999999876
+3 9.67080000000009e-05 0.0012490219999999885
+4 0.00011765699999999324 0.0013666789999999818
+5 4.965899999997969e-05 0.0014163379999999615
+6 8.666900000003919e-05 0.0015030070000000006
+   ...
+
+
+
+
+

status.pickle

+

If algorithm.checkpoint is set to true, the intermediate states are stored to status.pickle (or the filename specified by the algorithm.checkpoint_file parameter) for each MPI process in its subfolder. +They are read when the execution is resumed. +The content of the file depends on the algorithm.

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/search.html b/manual/v3.0.0/en/search.html new file mode 100644 index 00000000..1cee42e0 --- /dev/null +++ b/manual/v3.0.0/en/search.html @@ -0,0 +1,79 @@ + + + + + + + Search — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + + + + + +
+ + +

Search

+ + + + +

+ Searching for multiple words only shows matches that contain + all words. +

+ + +
+ + + +
+ + +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/searchindex.js b/manual/v3.0.0/en/searchindex.js new file mode 100644 index 00000000..76e1e866 --- /dev/null +++ b/manual/v3.0.0/en/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"alltitles": {"(For developers) User-defined algorithms and solvers": [[10, null]], "About the number of steps": [[6, "about-the-number-of-steps"]], "Acknowledgements": [[0, null]], "Adding a direct problem solver": [[29, null]], "Affine": [[9, "affine"]], "Algorithm": [[2, "algorithm"], [6, "algorithm"], [8, null], [8, "id1"]], "Algorithm Description": [[1, "algorithm-description"]], "AlgorithmBase": [[8, "algorithmbase"]], "Annealed Importance Sampling (AIS) [1]": [[6, "annealed-importance-sampling-ais-1"]], "BayesData.txt": [[1, "bayesdata-txt"]], "Bayesian optimization bayes": [[1, null]], "Calculation": [[21, "calculation"], [22, "calculation"], [25, "calculation"], [28, "calculation"]], "Calculation execution": [[26, "calculation-execution"], [27, "calculation-execution"]], "ColorMap.txt": [[4, "colormap-txt"]], "Common file": [[16, "common-file"]], "Commons": [[9, null]], "Contact": [[7, null]], "Contents:": [[13, null]], "Definition of Domain": [[8, "definition-of-domain"]], "Direct Problem Solver": [[18, null]], "Direct parallel search mapper": [[4, null]], "Goal": [[6, "goal"]], "Grid search": [[26, null]], "How to add a direct problem solver": [[29, "how-to-add-a-direct-problem-solver"]], "How to download and install": [[19, "how-to-download-and-install"]], "How to run": [[19, "how-to-run"]], "How to uninstall": [[19, "how-to-uninstall"]], "Inequality": [[9, "inequality"]], "Input file": [[14, null], [26, "input-file"], [27, "input-file"]], "Input files": [[21, "input-files"], [22, "input-files"], [25, "input-files"], [28, "input-files"]], "Input parameters": [[1, "input-parameters"], [2, "input-parameters"], [4, "input-parameters"], [5, "input-parameters"], [6, "input-parameters"], [17, "input-parameters"]], "Installation of ODAT-SE": [[19, null]], "Introduction": [[15, null]], "License": [[15, "license"]], "Location of the sample files": [[26, "location-of-the-sample-files"], [27, "location-of-the-sample-files"]], "Main developers": [[15, "main-developers"]], "Markov chain Monte Carlo": [[2, "markov-chain-monte-carlo"]], "Mesh definition file": [[1, "mesh-definition-file"], [2, "mesh-definition-file"], [4, "mesh-definition-file"], [6, "mesh-definition-file"]], "MeshGrid class": [[8, "meshgrid-class"]], "Minimization of an analytical function": [[24, null]], "Neighborhood-list file": [[2, "neighborhood-list-file"], [6, "neighborhood-list-file"]], "Nelder-Mead method minsearch": [[5, null]], "Optimization by Bayesian Optimization": [[21, null]], "Optimization by Nelder-Mead method": [[27, null]], "Optimization by population annealing": [[28, null]], "Optimization by replica exchange Monte Carlo": [[22, null]], "Output file": [[4, "output-file"]], "Output files": [[1, "output-files"], [2, "output-files"], [5, "output-files"], [6, "output-files"], [16, null]], "Population Annealing Monte Carlo pamc": [[6, null]], "Preparation": [[1, "preparation"], [2, "preparation"], [4, "preparation"], [5, "preparation"], [6, "preparation"]], "Prerequisites": [[19, "prerequisites"]], "RANK/result.txt": [[2, "rank-result-txt"], [6, "rank-result-txt"]], "RANK/result_T#.txt": [[6, "rank-result-t-txt"]], "RANK/trial.txt": [[2, "rank-trial-txt"], [6, "rank-trial-txt"]], "RANK/trial_T#.txt": [[6, "rank-trial-t-txt"]], "Reference file": [[1, "reference-file"], [2, "reference-file"], [6, "reference-file"]], "References": [[6, "references"]], "Refernce file": [[4, "refernce-file"]], "Region class": [[8, "region-class"]], "Related Tools": [[20, null]], "Replica Exchange Monte Carlo search with limitation": [[25, null]], "Replica exchange Monte Carlo": [[2, "replica-exchange-monte-carlo"]], "Replica exchange Monte Carlo exchange": [[2, null]], "Restart": [[1, "restart"], [2, "restart"], [4, "restart"], [5, "restart"], [6, "restart"]], "Sample files": [[21, "sample-files"], [22, "sample-files"], [28, "sample-files"]], "Sample files location": [[25, "sample-files-location"]], "Search algorithms": [[3, null]], "SimplexData.txt": [[5, "simplexdata-txt"]], "Solver": [[11, null]], "Solver for benchmarking, analytical": [[29, "solver-for-benchmarking-analytical"]], "TrivialMapping": [[9, "trivialmapping"]], "Tutorials": [[23, null]], "Unlimited": [[9, "unlimited"]], "Usage": [[12, null], [20, "usage"]], "Version Information": [[15, "version-information"]], "Visualization": [[21, "visualization"], [22, "visualization"], [28, "visualization"]], "Visualization of calculation results": [[26, "visualization-of-calculation-results"], [27, "visualization-of-calculation-results"]], "Visualization of the calculation result": [[25, "visualization-of-the-calculation-result"]], "Welcome to ODAT-SE documentation!": [[13, null]], "What is ODAT-SE ?": [[15, "what-is-odat-se"]], "[algorithm.bayes] section": [[1, "algorithm-bayes-section"]], "[algorithm.exchange]": [[2, "algorithm-exchange"]], "[algorithm.pamc]": [[6, "algorithm-pamc"]], "[algorithm.param]": [[2, "algorithm-param"], [6, "algorithm-param"]], "[algorithm.param] section": [[1, "algorithm-param-section"]], "[algorithm] section": [[14, "algorithm-section"]], "[base] section": [[14, "base-section"]], "[limitation] section": [[14, "limitation-section"]], "[log] section": [[14, "log-section"]], "[minimize] section": [[5, "minimize-section"]], "[param] section": [[4, "param-section"], [5, "param-section"]], "[runner.mapping] section": [[14, "runner-mapping-section"]], "[runner] section": [[14, "runner-section"]], "[solver] section": [[14, "solver-section"]], "analytical solver": [[17, null]], "base items": [[9, "base-items"]], "best_result.txt": [[2, "best-result-txt"], [6, "best-result-txt"]], "fx.txt": [[6, "fx-txt"]], "odatse.Info": [[9, "odatse-info"]], "odatse.Limitation": [[9, "odatse-limitation"]], "odatse.Mapping": [[9, "odatse-mapping"]], "odatse.Runner": [[9, "odatse-runner"]], "odatse_neighborlist": [[20, "odatse-neighborlist"]], "population annealing (PA) [2]": [[6, "population-annealing-pa-2"]], "res.txt": [[5, "res-txt"]], "result_T#.txt": [[2, "result-t-txt"]], "runner.log": [[16, "runner-log"]], "status.pickle": [[16, "status-pickle"]], "time.log": [[16, "time-log"]]}, "docnames": ["acknowledgement", "algorithm/bayes", "algorithm/exchange", "algorithm/index", "algorithm/mapper_mpi", "algorithm/minsearch", "algorithm/pamc", "contact", "customize/algorithm", "customize/common", "customize/index", "customize/solver", "customize/usage", "index", "input", "introduction", "output", "solver/analytical", "solver/index", "start", "tool", "tutorial/bayes", "tutorial/exchange", "tutorial/index", "tutorial/intro", "tutorial/limitation", "tutorial/mapper", "tutorial/minsearch", "tutorial/pamc", "tutorial/solver_simple"], "envversion": {"sphinx": 64, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2}, "filenames": ["acknowledgement.rst", "algorithm/bayes.rst", "algorithm/exchange.rst", "algorithm/index.rst", "algorithm/mapper_mpi.rst", "algorithm/minsearch.rst", "algorithm/pamc.rst", "contact.rst", "customize/algorithm.rst", "customize/common.rst", "customize/index.rst", "customize/solver.rst", "customize/usage.rst", "index.rst", "input.rst", "introduction.rst", "output.rst", "solver/analytical.rst", "solver/index.rst", "start.rst", "tool.rst", "tutorial/bayes.rst", "tutorial/exchange.rst", "tutorial/index.rst", "tutorial/intro.rst", "tutorial/limitation.rst", "tutorial/mapper.rst", "tutorial/minsearch.rst", "tutorial/pamc.rst", "tutorial/solver_simple.rst"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"": [5, 6, 9, 14, 15, 29], "0": [1, 2, 4, 5, 6, 8, 9, 11, 14, 15, 16, 17, 19, 20, 21, 22, 24, 25, 26, 27, 28, 29], "000": 14, "000000": [1, 2, 4, 6, 26, 27], "0000128043523089": 29, "0001": 21, "00010188398524402734": 25, "00011765699999999324": 16, "000595873999941432": 16, "0009563499997966574": 16, "0010": 15, "0010826379999999691": 16, "0011523139999999876": 16, "0012490219999999885": 16, "0013666789999999818": 16, "0014163379999999615": 16, "0015030070000000006": 16, "00319999999994": 21, "004999999999999999": 2, "006001660077530159": 5, "007259890999989693": 16, "008233957976993406": [2, 6], "01": [15, 22, 28], "01123654800138751": 22, "011301": 15, "01258925411794167": 28, "012626001098748564": 22, "012635279378225261": 5, "013002": 15, "013702918021532375": 5, "014187266741165962": 22, "015199251773721183": 5, "015848931924611134": 28, "01594159037455999": 22, "01791284454622004": 22, "0193077565358273": 6, "01995262314968879": 28, "02": [15, 22], "020127853758499396": 22, "022616759492228647": 22, "02312528177606794": 1, "023477428315198": 28, "025118864315095794": 28, "025413430367026365": 22, "026704": [6, 15], "028555923019901074": 22, "03": 15, "032086999973704504": 22, "037237": 21, "037237314010261195": 21, "038905": 4, "04": 15, "0420053981467825": 22, "04380131351780189": 1, "047674": 4, "047852": 4, "0479484091458": [22, 28], "05": 16, "051199999999973": 21, "051200000000003215": 21, "05141906746102885": 1, "053190": 4, "053675": 4, "055011": 4, "06": [5, 22, 28], "061261": 4, "0625": 27, "06273922648753057": 2, "06591878368102033": 1, "065919": 4, "069351": 4, "071868": 4, "0758494287185766": 2, "07830821484593968": 2, "08": [15, 27], "08566823949124412": 2, "1": [1, 2, 4, 5, 8, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 24, 25, 26, 27, 28, 29], "10": [15, 21, 22, 25, 28], "100": [1, 6, 17, 22, 25, 28], "1000": [2, 25], "10000": [5, 21, 22, 25], "100000": [5, 25], "1001st": 2, "1016": 15, "101st": 1, "104": 14, "10720000000002": 21, "108": [22, 28], "108371": 15, "108405": 15, "108465": 15, "11": [6, 15, 17, 24], "111": 21, "113": 21, "118822390166315": 28, "12": 15, "121600": 26, "12320000000045": 21, "12345": [21, 22, 25, 26, 27, 28, 29], "125": [6, 15], "13": 6, "130": [21, 28], "1306": 21, "131045687296453": 28, "131312": [17, 24], "137": 15, "139": [6, 15], "139591716517661": [2, 6], "14": 19, "1465364357510186": [22, 28], "148": 25, "15": [2, 15], "150": 21, "155393113805774": [22, 25, 28], "16": 14, "1604": 15, "16320000000003": 21, "17": [15, 22], "170": 22, "178": 21, "179380982615041": [22, 28], "179976851851851": 5, "1806": 28, "187": [22, 25, 28], "188": 15, "19": [15, 19], "191": 15, "1972": 24, "1986": 15, "1993": 15, "1996": 15, "1999999999999993": 21, "19h04125": 0, "1e": 5, "2": [1, 2, 4, 5, 12, 14, 15, 16, 17, 19, 21, 22, 24, 25, 26, 27, 28, 29], "20": [1, 17, 21, 22, 25, 26, 27, 28], "200": [1, 6, 15], "2000": 2, "200000": 26, "200000000000001": 21, "2000th": 2, "2001": [6, 15], "20027165958588": 28, "2003": [6, 15], "2006": 15, "200th": 1, "2010": [6, 15], "20146188151557": 28, "2019": 15, "2020": 15, "2021": [0, 15], "2022": 15, "2023": 15, "2024": [0, 15], "203493345018569": [22, 25, 28], "2093903670436497": 2, "20946994566609": 2, "20h00581": 0, "21": 28, "2134775491597027": 6, "216": 14, "2192": 21, "21k19773": 0, "22": 21, "221129370933539": [2, 6], "225694444444445": 5, "2278370361994904e": 27, "229": 15, "229166666666666": 5, "23": 21, "230524973874179": 5, "23606736778044": 25, "23k18465": 0, "240": 26, "241600": 26, "25": [1, 5, 15], "250000": [1, 2, 4, 6], "252": 15, "25390522675298": 28, "25464277273859": [22, 28], "2607": 15, "263": 21, "27": 21, "277": 15, "2770369776964151": 6, "278": 15, "28": [2, 21], "280": 15, "283186": [17, 24], "2971072297035158": 28, "2d": [25, 28], "2dmat": [0, 7, 15], "2x": 29, "2y": 29, "3": [1, 2, 4, 5, 6, 12, 14, 15, 16, 17, 19, 21, 22, 24, 25, 26, 27, 28, 29], "30000": 21, "31": [14, 26], "311333132184154": 2, "3125": 5, "3139009347685118": 2, "314159": 14, "32": 28, "321623766458111": 6, "3224223930001244": 16, "328125": 27, "33": [6, 22], "330": [22, 28], "330900869594549": 2, "337600": 26, "3377081691728905": 22, "34": 6, "345600": 26, "3479083531465976": 28, "348958333333334": 5, "3493346729999303": 16, "35": 22, "354500581633733": 6, "358076734724385e": 22, "360": 14, "36426034198166": 6, "370212436322816": 25, "370622919269477": 5, "375": 27, "38": [21, 29], "382680568652868e": 5, "39": [6, 21], "3952000000000133": 21, "39908953806298": 28, "39999999999999947": 21, "3999999999999995": 21, "4": [1, 2, 4, 5, 6, 12, 15, 16, 21, 22, 25, 26, 27, 28], "40": [1, 21, 22, 27], "400": 28, "400000": 26, "40625": 5, "40963740872147": 22, "41": [21, 27, 28], "4155554347674215": [22, 28], "41st": 21, "42": 21, "433599999999999": 21, "43633134370869153": [22, 28], "44": 21, "45": [22, 28], "452": [22, 28], "4523": 25, "4541906604820898": 22, "457599999999996": 21, "45919999999997": 21, "4655": 15, "466110964691396": [22, 28], "46875": 27, "4691017123836": [22, 28], "47": 28, "481600": 26, "483": [22, 28], "487174782058675": 6, "5": [1, 2, 4, 5, 6, 15, 16, 20, 21, 22, 25, 26, 28, 29], "5000": [1, 21], "50000": 21, "500000": [1, 2, 4, 6], "5034551820852": 22, "518006242920819": 6, "52": 15, "5259": 15, "5355817998709": [22, 28], "535680832873856": [22, 28], "538611313376179": 6, "5426399088244793": 28, "5451388888888884": 5, "5452766573635235": [22, 28], "552": [22, 28], "57": 15, "57417423682746": [22, 28], "575771168463163": [22, 28], "584428": [17, 24], "584944906595298": 25, "5919146358616842": 6, "592321856342956": 6, "5943287037037033": 5, "5961444501081647": 5, "5999999999999996": 21, "6": [1, 2, 4, 6, 15, 16, 21, 22, 25, 26, 27, 28, 29], "60": 28, "600000": 26, "6000000000000005": 21, "600000000000001": 21, "6000000000000014": 21, "606664760390988": 2, "609443449748964": 28, "61": 21, "610": 26, "619200000000067": 21, "622": 26, "623": 21, "626": 26, "6274790817115": 28, "645833333333333": 5, "65": [2, 6, 15, 21], "65151610695736": 6, "65625": 27, "661": 26, "666900000003919e": 16, "667": 26, "6672": 21, "67080000000009e": 16, "672488908364282": 6, "682008067401509": 2, "684224163039442": [22, 28], "690": [6, 15], "691101784194861": 2, "7": [1, 2, 4, 5, 6, 15, 17, 21, 22, 24, 26, 28, 29], "70157662892569": 2, "705600000000004": 21, "7097039347500953": 28, "711": 26, "717750630491217": [22, 28], "719": [22, 28], "722667479627368": [22, 28], "729600": 26, "73": 6, "73578884504734": 28, "739200000001": 21, "74": 28, "7442621319489637": 2, "748689609377718e": 28, "75": [1, 29], "750000": [1, 2, 4, 6], "753": 26, "7552": 21, "7680892360649545": 28, "769600": 26, "770": 26, "777": 14, "779310": [17, 24], "79": 27, "7929742598748666": [22, 28], "7972369561986": [22, 28], "7992581349758": [22, 28], "7999999999999998": 21, "8": [1, 2, 4, 6, 15, 16, 21, 22, 28], "80": 22, "800000": 26, "8000000000000007": 21, "800000000000001": 21, "8025": 22, "805118": [17, 24], "805353724219707": 28, "81": 22, "811346329442423": 2, "8127003489802398": [22, 28], "82": [6, 15], "8214854089575818": 28, "82799488298886": 6, "83": 28, "834671825646121": 6, "83620542622489": 28, "8381251624588506": [22, 28], "84183395038843": [22, 28], "8428384502208246": [22, 28], "848126": [17, 24], "8506985826548874": 25, "859375": 27, "868754990884034": 2, "8736706475438123": 22, "8769341969872393": [22, 28], "890": 26, "899340424701358": [22, 28], "9": [1, 2, 4, 6, 15, 16, 19, 21, 22, 28], "90000": 21, "9004": 6, "9058": 6, "908794428939206": 6, "910894059585031": 6, "913851603463": 6, "9153": 28, "93": 22, "930325": 28, "93715": 28, "9375": 27, "9378": 28, "940375": 28, "94429125133564": [22, 25, 28], "9502750191292586": 2, "9535301415484388": 6, "96292704464803": 6, "965899999997969e": 16, "96760000000185e": 16, "972577711255287": [22, 28], "9804": 6, "9862114670289625": 28, "98676409223712": 2, "9868796504069426": [22, 28], "995199999999958": 21, "9995614992887525": 25, "999754886043102": 22, "9998063442504126": 22, "9999669562950175": 27, "9999832920260863": 29, "9999973389336225": 27, "A": [0, 1, 2, 4, 6, 8, 9, 14, 15, 20, 21, 25, 26, 27], "As": [2, 9, 14, 15, 24, 25, 29], "At": [1, 19], "By": [2, 6, 21, 22, 25, 26, 27, 28], "For": [0, 1, 2, 4, 5, 6, 8, 13, 14, 15, 19, 21, 22, 25, 26, 28, 29], "If": [1, 2, 4, 5, 6, 7, 8, 9, 14, 16, 19, 22, 25, 28], "In": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 14, 15, 19, 21, 22, 23, 25, 26, 27, 28], "It": [1, 2, 5, 6, 8, 9, 11, 12, 14, 15, 19, 21, 22, 24, 25, 27, 28], "On": [1, 2], "One": [2, 6, 11, 14], "Or": 20, "The": [0, 1, 2, 4, 5, 6, 8, 9, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 24, 25, 26, 27, 28, 29], "Then": [1, 2, 6, 9, 21, 22, 25, 27, 28], "There": [6, 11], "These": [16, 22, 28], "To": [2, 7, 14, 19, 29], "With": 29, "_": [1, 2, 6], "_0": 6, "_1": 6, "__call__": 9, "__init__": [8, 11, 29], "_at_": 7, "_histogram": 25, "_i": [1, 6], "_n": 6, "_post": 8, "_prepar": 8, "_run": 8, "_t": 2, "abic": 0, "about": [1, 2, 5, 7, 14, 16, 22, 25, 28], "abov": [2, 21, 26, 27], "absolut": 9, "ac": 7, "accept": [2, 6, 11, 28], "accord": [2, 5, 6], "accumul": 11, "accuraci": [1, 6], "achiev": 2, "acklei": 17, "acknowledg": 13, "acquit": 1, "acta": 15, "action": 21, "actual": [9, 22, 25, 28], "ad": [0, 1, 13, 23], "add": [15, 22, 25, 28], "addit": [1, 11, 14, 21, 23, 27], "addition": 25, "address": 7, "adopt": [2, 22, 25, 28], "advanc": [0, 4, 15], "affin": 14, "after": [1, 2, 8, 20, 25], "aid": 1, "aip": [6, 15], "akimoto": 15, "al": 15, "algorithm": [4, 5, 9, 11, 12, 13, 15, 16, 17, 19, 21, 22, 23, 24, 25, 26, 27, 28, 29], "algorithmbas": 12, "all": [2, 4, 5, 6, 7, 15, 19, 20, 25, 26, 27], "allow": [1, 20, 29], "allpair": 20, "allvec": 27, "along": [21, 26], "alreadi": 1, "also": [2, 12, 14, 20, 21, 25], "altern": 9, "although": [5, 6, 27], "alwai": 9, "among": [2, 6, 24], "amount": 1, "an": [1, 2, 4, 5, 6, 7, 8, 9, 11, 13, 14, 15, 16, 20, 22, 23, 25, 27, 28, 29], "analys": [19, 23, 27], "analysi": [9, 15, 19, 21, 27], "analyt": [13, 14, 18, 21, 22, 23, 25, 26, 27, 28], "analyz": [26, 29], "ancestor": [6, 28], "ani": [7, 9], "anneal": [2, 3, 13, 14, 15, 23], "anoth": 2, "answer": [1, 25], "aoyama": 15, "appl": 15, "appli": [9, 11, 15, 23, 24, 25], "applic": 15, "approxim": 1, "ar": [1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 25, 26, 27, 28], "arg": [8, 9, 11], "argument": [8, 9, 11, 20], "argv": 12, "arithmet": 6, "arrang": 14, "articl": 15, "assign": [2, 4, 6], "assum": [5, 6, 9, 21, 22, 25, 26, 27, 28], "atom": 15, "attempt": 25, "author": 15, "autom": 15, "automat": [4, 6, 8, 9], "avail": [1, 2, 6, 12, 14, 16, 17, 20, 21, 22, 25, 28], "avoid": 2, "aw_n": 6, "ax": [8, 14, 25], "axi": 28, "b": [9, 14, 25], "balanc": [1, 2, 6], "bar": 20, "barbieri": 15, "base": [1, 8, 11, 13, 21, 22, 25, 26, 27, 28, 29], "bash": 25, "basi": 1, "basic": 14, "bay": [3, 13, 14, 21, 23], "bayes_max_num_prob": [1, 21], "bayesdata": 21, "bayesian": [3, 13, 14, 15, 23], "baysian": 19, "becaus": [1, 2, 6, 22, 25, 27], "becom": [2, 28], "been": [1, 2, 4, 6, 15], "befor": [1, 2, 6, 8, 21], "beforehand": [1, 21], "begin": [1, 6, 14, 25, 28], "behavior": 8, "being": [5, 25], "below": [1, 2, 4, 5, 6, 19], "benchmark": [17, 24], "benefici": 1, "best": [1, 21, 25], "best_result": [22, 25, 28], "beta": [2, 6, 28], "beta_0": 6, "beta_i": 6, "better": 1, "between": [1, 2, 6, 14, 15, 22, 25, 28], "bias": 2, "bibtex": 15, "big": 6, "bin": [20, 25], "black": 27, "blue": 27, "bmax": [2, 6, 28], "bmin": [2, 6, 28], "bo": [1, 21], "bodi": 8, "boltzmann": 2, "bolzmann": 6, "bool": [8, 9], "boolean": [2, 6, 14], "booth": 29, "both": [1, 14, 25], "bound": [8, 22, 25, 28], "branch": 29, "bridg": 14, "briefli": [22, 28], "bug": 7, "bulk": 26, "burn": 25, "c": 15, "calcul": [1, 2, 5, 6, 9, 14, 15, 16, 18, 20], "call": [1, 2, 6, 8, 11, 14, 16, 27], "can": [1, 2, 4, 6, 9, 10, 11, 15, 19, 21, 22, 23, 25, 26, 27, 28, 29], "candid": [1, 2, 4, 21, 27], "cannot": 2, "carefulli": 2, "carlo": [3, 11, 13, 14, 15, 23, 28], "carri": [1, 2, 19], "case": [2, 4, 9, 14, 21, 25, 26, 27, 28, 29], "cd": [21, 22, 25, 26, 27, 28], "cdot": 6, "center": [2, 19], "chain": 6, "chang": 22, "chapter": [10, 21, 26, 27], "check": [5, 9, 20, 25], "checkpoint": [1, 2, 4, 6, 8, 14, 16], "checkpoint_fil": [8, 14, 16], "checkpoint_interv": [8, 14], "checkpoint_step": [8, 14], "choos": [1, 2, 29], "chosen": 1, "cite": 15, "cl": 8, "class": [9, 11, 12, 29], "climb": 2, "clone": 19, "co": 17, "co_a": [14, 25], "co_b": [14, 25], "code": [6, 9, 19, 29], "coeffici": 9, "color": [26, 28], "colormap": 26, "colormapfig": 26, "column": [1, 2, 4, 6, 16, 21, 22, 25, 26, 28], "com": [15, 19], "combin": [6, 10], "comm": 8, "comm_world": 8, "command": [1, 2, 4, 6, 19, 20, 21, 22, 25, 26, 27, 28], "comment": [4, 12], "common": [8, 10, 13], "commonli": 9, "commun": 15, "compar": 25, "compat": 26, "compil": 7, "complex": 15, "compon": [5, 9, 10], "comput": [1, 4, 6, 15, 16, 17, 26, 27], "concatn": 28, "concentr": [22, 28], "concern": 8, "concret": 8, "condit": [1, 2, 4, 6], "conf": [6, 15], "configur": [6, 14], "confirm": 25, "connect": 9, "consequ": 6, "consid": [1, 2, 5, 6, 20], "consist": 14, "constraint": [8, 9, 14, 25], "constructor": [1, 2, 4, 6, 8, 9, 11, 12, 29], "consult": 7, "cont": [1, 2, 4, 6], "contact": 13, "contain": [1, 4, 8, 9, 21, 22, 25, 26, 28], "content": [16, 21, 22, 26, 28], "continu": [1, 2, 4, 6, 8], "contour": [21, 26, 27], "contribut": 1, "conveni": 19, "converg": [2, 5, 27], "convert": 9, "cool": 2, "cooper": 7, "coordin": [1, 2, 4, 5, 6, 20, 25], "copi": 2, "copyright": 15, "core": [22, 25, 28], "correct": [1, 21], "correctli": 25, "correspond": [1, 2, 4, 6, 8, 9, 11, 12, 14, 20, 21, 28], "count": 11, "counter": [1, 2], "cours": 12, "cpc": 15, "creat": [1, 4, 5, 8, 9, 21, 22, 25, 26, 28], "current": [2, 9, 11, 14, 15, 21, 25, 27], "curv": 27, "custom": 0, "d": [5, 6, 15, 24, 29], "dai": 14, "dat": 27, "data": [1, 4, 8, 11, 15, 19, 22, 25], "dataset": 1, "date": 25, "debug": 20, "decreas": [2, 28], "deeper": 2, "def": [11, 29], "default": [1, 2, 4, 5, 6, 8, 9, 14, 20, 25, 26, 27], "defin": [1, 2, 4, 5, 6, 8, 9, 11, 12, 13, 14, 15, 19, 23, 25, 29], "delta": 2, "denot": [25, 28], "depart": 15, "depend": [8, 16], "deriv": 11, "descend": 2, "descent": 5, "describ": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 21, 22, 23, 25, 26, 27, 28], "descript": [2, 4, 5, 6, 8, 14, 17], "design": 0, "detail": [2, 5, 6, 8, 9, 14, 19, 21, 22, 25, 26, 27, 28, 29], "determin": [2, 5, 6, 14, 15], "dev": 19, "dev__at__issp": 7, "develop": [0, 13, 19], "deviat": [2, 6, 15, 22, 25, 28], "diagram": 22, "dict": [8, 9, 12], "dictinari": 8, "dictionari": [8, 9], "diff": 25, "differ": [2, 5, 6, 22, 25], "difficult": [6, 7], "diffract": [14, 15, 19], "dilemma": 2, "dim": 20, "dimens": [1, 2, 4, 5, 6, 8, 14, 20, 21, 22, 25, 26, 27, 28, 29], "dimension": [9, 11, 14, 15, 19, 22, 25, 26, 28], "dimensionless": 5, "dirctori": 9, "direct": [3, 9, 10, 11, 13, 14, 15, 16, 19, 23, 24, 27], "directli": [2, 6, 19, 25, 26, 27], "directori": [8, 9, 11, 14, 21, 22, 25, 26, 27, 28], "disabl": 8, "discard": 25, "discret": [2, 6, 8], "discuss": 24, "distanc": 20, "distribut": [2, 6, 8, 15, 22, 25, 28], "divid": [1, 4, 5, 6, 8, 20, 25], "do": [1, 9, 20, 21, 22, 25, 26, 27, 28, 29], "do_split": 8, "document": 5, "doe": [1, 2, 9], "doi": 15, "done": [1, 2, 5, 6, 14, 26, 27], "dot": 6, "downhil": 5, "download": [13, 25, 26, 27, 29], "draw_from": 6, "drawn": 27, "due": 2, "dure": [1, 2, 5, 6, 7, 21, 27], "e": [2, 6, 7, 15, 17, 20], "each": [1, 2, 4, 5, 6, 8, 9, 11, 14, 16, 20, 21, 22, 25, 26, 27, 28], "earli": 7, "easi": [1, 2], "easiest": 29, "easili": 2, "echo": 25, "edit": 29, "ei": 1, "either": 14, "elaps": [8, 16], "elapsed_time_from_last_cal": 16, "elapsed_time_from_start": 16, "electron": [14, 19], "element": [9, 14], "elif": 29, "els": 25, "empti": [8, 14], "enabl": [1, 2, 4, 6, 8, 14], "end": [1, 2, 4, 6, 14, 23, 25], "endur": 2, "energi": [14, 15, 19], "engin": 15, "enough": 1, "enter": [7, 8], "entir": 23, "eq": 25, "equal": [2, 4, 5, 6, 14, 24, 25], "equat": 2, "equiv": 6, "ergod": 2, "error": [1, 6, 28, 29], "escap": 2, "estim": [6, 15, 21, 22, 26, 27, 28], "et": 15, "etc": 14, "euclidean": 20, "evalu": [1, 2, 4, 5, 6, 11, 14, 17, 21, 22, 24, 25, 26, 27, 28, 29], "evenli": [1, 4], "everi": [14, 27], "exactli": 1, "exampl": [1, 2, 4, 5, 6, 8, 12, 14, 16, 22, 23, 24, 25, 29], "exce": [2, 5, 6], "exchang": [3, 13, 14, 15, 23], "execut": [1, 2, 4, 6, 7, 8, 9, 11, 14, 16, 19, 21, 22, 25, 28], "exp": [2, 6, 17], "expand": 9, "expandus": 9, "expect": [1, 6, 29], "experi": 15, "experiment": [15, 19], "explain": [23, 25, 26, 27, 29], "exploit": 1, "explor": [1, 2, 4, 6, 22, 28], "express": [9, 25], "extend": 6, "extern": 11, "extra": 25, "f": [1, 2, 3, 4, 6, 8, 9, 17, 18, 21, 22, 24, 28, 29], "f_": 6, "f_0": 6, "f_i": 6, "f_n": 6, "fact": 2, "factor": [1, 2, 5, 6, 21, 28], "factor_act": 1, "fail": [8, 25], "fall": [2, 5, 6], "fals": [14, 25], "far": 1, "fatol": 5, "featur": 8, "few": [21, 22, 26, 27, 28], "fi": 25, "field": [8, 9, 11], "fifth": [6, 22, 28], "figur": [22, 25, 28], "file": [7, 8, 9, 11, 12, 13, 19, 20, 29], "file_cm": 16, "filenam": [14, 16, 20], "fill": [22, 28], "final": [2, 5, 6, 14, 21, 25, 26, 27, 28], "find": [5, 15], "finish": [1, 8], "first": [1, 2, 4, 5, 6, 16, 21, 22, 25, 26, 27, 28, 29], "fix": [2, 6], "fix_num_replica": 6, "float": [1, 2, 4, 5, 6, 9, 11, 14, 29], "flow": 12, "folder": [21, 22, 25, 26, 27, 28], "follo": [1, 2, 4, 6], "follow": [1, 2, 4, 5, 6, 7, 8, 9, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29], "footnot": 2, "forall_i": 17, "form": [2, 6, 8, 9, 11, 14], "format": [1, 2, 4, 5, 6, 9, 12, 14, 17, 21, 22, 25, 27, 28], "former": 1, "found": [26, 27], "four": [9, 14], "fourth": [2, 6, 21, 22, 25, 28], "frac": [2, 6, 17], "framework": 15, "frequenc": 27, "from": [1, 2, 4, 5, 6, 8, 9, 11, 14, 19, 20, 21, 22, 23, 26, 27, 28, 29], "from_dict": 9, "from_fil": [8, 9, 12], "fukaya": 15, "function": [1, 2, 4, 5, 6, 8, 9, 11, 13, 15, 17, 18, 21, 22, 23, 25, 26, 27, 28, 29], "function_nam": [17, 21, 22, 25, 26, 27, 28, 29], "funtion_nam": 17, "further": 15, "fusion": 15, "futur": 15, "fx": [2, 5, 8, 21, 22, 25, 27, 28], "fx_action": 21, "fy2020": 0, "g": [1, 6, 15, 20], "gaussian": [1, 2, 6, 22, 25, 28], "gave": 21, "gener": [2, 6, 8, 14, 20, 21, 22, 25, 26, 27, 28], "generet": 6, "get": [6, 9], "git": 19, "github": [7, 19], "give": [1, 2, 15, 21], "given": [2, 5, 6, 8, 9, 11, 14, 15, 23, 24, 25], "global": 29, "goe": 2, "grand": [6, 28], "grant": 0, "greater": 25, "grid": [1, 2, 4, 6, 8, 11, 13, 14, 15, 19, 21, 23], "guidelin": 7, "h": 15, "ha": [1, 2, 4, 5, 6, 9, 12, 14, 15, 25, 28, 29], "hanada": 15, "hand": [1, 2], "handl": 22, "harumichi": 15, "hast": 2, "have": [1, 7, 8, 9, 11, 22, 24, 25, 28], "hayato": 15, "header": 5, "heat": 2, "height": 2, "helper": 8, "here": [22, 26, 27, 28], "hereinaft": [21, 22, 28], "high": [14, 15, 19, 22], "higher": 19, "highest": 21, "hill": [2, 24], "himmelblau": [21, 22, 24, 25, 26, 27, 28, 29], "himmerblau": 17, "hisada": 15, "hist2d_limitation_sampl": 25, "histogram": 25, "histori": 21, "hold": [6, 22], "home": [9, 19], "hope": 15, "horizont": [25, 28], "hoshi": 15, "hove": 15, "how": [1, 9, 10, 11, 13, 21, 22, 23, 26, 27, 28], "http": [15, 19], "hukushima": [6, 15], "hyodo": 15, "hyper": [1, 2, 22], "hyperparamet": [1, 5, 21, 25], "i": [0, 1, 2, 4, 5, 6, 8, 9, 11, 12, 13, 14, 16, 17, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29], "iba": [6, 15], "ichimiya": 15, "ichinos": 15, "ident": 14, "ignor": [2, 4, 6], "illustr": 28, "implement": [1, 3], "import": [1, 2, 5, 8, 11, 12], "impos": [2, 9, 25], "imposs": 2, "improv": 1, "includ": [19, 20, 21, 22, 24, 28, 29], "increas": [1, 2], "index": [1, 2, 4, 6, 11, 21, 22, 28], "indic": [2, 6, 9, 28], "inequ": 14, "infinit": [2, 5, 6], "info": [8, 11, 12], "inform": [1, 5, 7, 8, 13, 16, 22, 28], "init": [1, 2, 4, 6], "initi": [1, 2, 4, 5, 6, 8, 9, 14, 21, 27], "initial_list": [2, 5, 6, 27, 29], "initial_scale_list": 5, "initial_simplex": 5, "input": [7, 8, 9, 11, 12, 13, 16, 19, 29], "input_fil": 12, "insert": 29, "insid": 27, "inspir": 0, "instal": [1, 2, 4, 5, 6, 7, 13, 20, 21, 29], "instanc": [8, 9, 11], "instanti": 12, "instead": [6, 10, 19, 26], "insteadli": 2, "institut": [0, 15], "instruct": [19, 29], "int": [6, 8, 9, 11], "integ": [1, 2, 4, 5, 6, 11, 14, 16], "intens": 14, "intermedi": [1, 2, 4, 6, 11, 14, 16], "intern": [9, 25], "interrupt": [1, 8], "interv": [1, 2, 6, 14, 16, 21, 26, 27, 28], "introduc": [6, 11, 25], "introduct": 13, "invers": [2, 6, 9, 10, 15, 23, 27, 28], "invok": [9, 12], "issn": 15, "issp": [0, 19], "issu": 7, "iter": [1, 2, 5, 11, 14, 26, 27, 29], "its": [7, 15, 16, 21, 22, 26, 27, 28], "itself": 20, "iwamoto": 15, "izumi": 15, "j": [2, 6, 15], "japan": 15, "jarzynski": [6, 28], "jjap": 15, "joint": 6, "journal": 15, "jp": 7, "jsp": 0, "judg": 9, "judgment": 27, "just": [2, 6], "k": [0, 5, 6, 15], "kakenhi": 0, "kawata": 15, "kazuyoshi": 15, "kei": [2, 6], "kept": [1, 2, 4, 6, 14], "kernel": 1, "known": 2, "label_list": 8, "langl": 6, "larg": [1, 6, 14], "last": [4, 6, 16], "latest": [1, 2, 4, 6, 14], "latter": 1, "le": 2, "lead": [2, 9], "learn": 1, "least": [14, 21], "leed": [14, 15, 19], "left": [2, 6, 14, 17, 21, 28], "len": 27, "length": [1, 2, 4, 5, 6, 20, 22, 25, 28], "less": [14, 20], "let": 2, "lett": 15, "librari": 1, "licens": 13, "like": [1, 26], "limit": [8, 13, 23], "line": [1, 4, 5, 20, 25, 27, 29], "linear": [1, 9, 14], "list": [1, 4, 5, 8, 14, 16, 20, 21], "littl": 1, "local": [2, 5, 14, 19], "locat": [11, 21, 22, 28], "log": [6, 21, 22, 25, 26, 27, 28], "logarithm": [2, 6, 22, 28], "long": [1, 14], "look": [21, 22], "loss": 15, "low": [14, 19, 22], "lower": [6, 8, 22, 25, 28], "m": [1, 2, 4, 5, 6, 9, 14, 15, 19, 25], "machin": 1, "machta": [6, 15], "made": 8, "mai": [1, 9, 29], "mail": 7, "main": [8, 12, 13, 21, 22, 25, 26, 27, 28], "mainli": 14, "make": [26, 29], "mani": 2, "manner": 8, "manual": [9, 21, 22, 25, 26, 27, 28], "map": 26, "mapper": [3, 8, 13, 14, 26], "mapper_mpi": [1, 4, 23], "margin": 6, "markov": 6, "massiv": 2, "match": [1, 4, 5], "mater": 15, "materi": [0, 15, 19], "mathbf": 3, "mathemat": 15, "mathrm": 6, "matrix": [9, 14, 25], "max_list": [1, 2, 4, 5, 6, 14, 21, 22, 25, 26, 27, 28, 29], "maxfev": 5, "maximum": [1, 2, 4, 5, 6, 21, 22, 26, 27, 28], "maxit": 5, "mc": [2, 6, 11, 25, 28], "mcgraw": 24, "mcmc": 2, "mead": [3, 13, 14, 15, 19, 21, 22, 23, 26, 28, 29], "mean": [6, 14, 28], "measur": [8, 15], "member": 15, "mesh": [8, 20], "mesh_path": [1, 2, 4, 6], "meshdata": [20, 26], "method": [2, 3, 6, 8, 9, 10, 11, 12, 13, 14, 15, 19, 21, 22, 23, 25, 26, 28, 29], "metric": 6, "metropoli": 2, "mh": 2, "min": 2, "min_list": [1, 2, 4, 5, 6, 14, 21, 22, 25, 26, 27, 28, 29], "minim": [13, 15, 21, 22, 23, 25, 26, 27], "minima": [2, 22, 24, 27, 28], "minimum": [1, 2, 4, 5, 6, 14, 21, 22, 24, 26, 27, 28, 29], "minsearch": [2, 3, 8, 13, 14, 21, 22, 23, 26, 27, 28, 29], "mochizuki": 15, "mode": [1, 2, 4, 6, 8], "model": 1, "modifi": 29, "modul": 19, "modular": 15, "mont": [3, 11, 13, 14, 15, 23, 28], "more": [2, 5, 22, 28], "moreov": 2, "moritz": 15, "most": 2, "motoyama": 15, "motoyama2022108465": 15, "move": [2, 5, 6, 8, 21, 22, 25, 26, 27, 28], "mozilla": 15, "mpi": [1, 2, 4, 6, 8, 11, 14, 16, 20, 22, 25, 26, 28], "mpi4pi": [1, 2, 4, 6, 8, 19], "mpi_rank": 14, "mpicomm": 8, "mpiexec": [22, 25, 26, 28], "mpirank": [8, 11], "mpisiz": 8, "mpl": 15, "much": 1, "mukainakano": 15, "multipl": 24, "must": 19, "n": [1, 6, 9, 11, 14, 15, 17, 25], "nakatani": 15, "name": [0, 6, 8, 14, 15, 17, 21, 22, 25, 26, 27, 28, 29], "narrow": 2, "nation": 15, "ndarrai": [9, 11, 29], "ne": 14, "neal": [6, 15, 28], "nealder": 23, "necessari": 2, "need": [1, 4, 5, 19, 22, 29], "neg": 1, "neighborhood": 20, "neighborlist": 20, "neighborlist_path": [2, 6], "nelder": [3, 13, 14, 15, 19, 21, 22, 23, 26, 28, 29], "nelson": 5, "nemoto": 15, "new": 6, "newlin": 14, "next": [1, 2, 6, 14, 25, 29], "ni": 3, "node": 20, "non": 2, "none": 8, "nonlinear": 24, "normal": [1, 2, 5, 6, 21, 22, 25, 26, 27, 28], "note": [1, 2, 6], "np": [8, 9, 11, 22, 25, 26, 28, 29], "nproc": [2, 6, 11, 22, 25, 28], "nreplica_per_proc": [2, 6, 22, 28], "nthread": 11, "num_cal": 16, "num_list": [1, 4, 21, 26], "num_rand_basi": [1, 21], "num_walk": 8, "number": [0, 1, 2, 4, 5, 8, 11, 12, 14, 16, 21, 22, 24, 25, 26, 27, 28], "numer": 6, "numpi": [11, 14, 19], "numstep": [2, 6, 22, 25], "numsteps_ann": [6, 28], "numsteps_exchang": [2, 22, 25], "numt": 6, "o": [20, 21, 22], "obei": [2, 6], "object": [1, 5, 8, 9, 11, 22, 25, 28], "observ": 2, "obtain": [1, 2, 8, 9, 11, 15, 21, 22, 25, 26, 27, 28], "obtaind": 1, "occas": [1, 2, 4, 6], "occur": 7, "odat": [0, 1, 2, 3, 5, 7, 9, 10, 12, 14, 20, 21, 22, 23, 24, 28, 29], "odats": [1, 2, 4, 6, 8, 11, 12, 19, 21, 22, 28, 29], "odatse_main": [19, 21, 22, 25, 26, 27, 28, 29], "odatse_neighborlist": [2, 6, 13], "offer": [8, 15], "offici": 5, "often": 1, "omit": [9, 14, 27], "onc": 25, "one": [1, 2, 4, 5, 6, 14, 22, 25, 27, 28, 29], "ones": [2, 28], "onli": [1, 16, 25, 26, 27], "open": [15, 22, 28], "openmpi": 25, "oper": [1, 2, 4, 6, 7], "optim": [2, 3, 5, 6, 8, 10, 12, 13, 14, 15, 17, 18, 19, 23, 24, 25, 29], "optimum": 5, "option": [1, 2, 4, 6, 8, 19, 20, 22, 25, 28], "order": [1, 2, 4, 5, 6, 8], "org": 15, "organ": 15, "origin": [8, 14, 15], "other": [1, 2, 7, 11, 15, 21, 26, 27], "otherwis": [2, 6, 8], "our": 6, "out": [1, 2, 6, 14, 19], "output": [7, 8, 9, 11, 13, 14, 20, 21, 22, 25, 26, 27, 28, 29], "output_dir": [8, 9, 11, 14, 21, 22, 25, 26, 27, 28, 29], "over": [1, 2, 6, 9, 15, 22, 23], "overcom": [2, 6], "oversubscrib": [22, 25, 28], "own": 10, "p": [2, 6, 9, 15, 25], "packag": [15, 19, 20, 21], "page": [7, 15], "pair": [5, 20], "pamc": [3, 13, 14, 23, 28], "parallel": [1, 2, 3, 6, 11, 13, 20, 22, 25, 26, 28], "parallelis": 11, "param": [8, 21, 22, 25, 26, 27, 28, 29], "paramet": [3, 8, 9, 11, 12, 14, 15, 16, 18, 21, 22, 23, 25, 26, 27, 28, 29], "parametar": [1, 4], "parametr": 14, "part": [0, 4], "particularli": 1, "partit": [6, 28], "pass": [1, 2, 4, 6, 8, 9, 11, 12, 20, 25, 26, 29], "past": 14, "path": [1, 2, 4, 6, 8, 9, 11, 14, 20, 27], "pathlib": [8, 9, 11], "pc": [21, 22, 25, 26, 27, 28], "pdf": [21, 27, 28], "perform": [1, 2, 4, 5, 8, 17, 19, 22, 23, 25, 26, 27, 28], "period": [1, 2, 4, 6, 14, 25], "phy": [6, 15], "physbo": [1, 19, 21], "physic": [0, 15], "pi": [1, 17], "pickl": 14, "pii": 15, "pip": [1, 2, 4, 5, 6, 19, 20], "place": 1, "plan": 15, "platform": 15, "pleas": [2, 6, 7, 19, 26], "plot": [21, 22, 24, 25, 26, 27, 28], "plot_colormap_2d": 26, "plot_himmel": [21, 22, 27], "plot_result_2d": 28, "plot_result_2dmap": 28, "plu": 5, "png": [22, 26, 28], "point": [1, 2, 4, 5, 6, 8, 11, 14, 21, 22, 26, 27, 28, 29], "pol": 15, "popul": [3, 13, 14, 15, 23], "posit": [2, 15, 16], "positron": [14, 15, 19], "possibl": [1, 12], "post": [8, 16], "posterior": 25, "power": 1, "practic": 2, "pre": [8, 16], "precis": 2, "predefin": [17, 19, 26], "predetermin": 1, "prepar": [8, 12, 15, 16, 19, 25, 26, 27], "preprar": 8, "prerequisit": 13, "prescrib": 14, "present": 19, "previou": [1, 2, 6, 14], "probabl": [1, 2, 6, 25], "problem": [2, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15, 16, 19, 21, 22, 23, 24, 25, 26, 27, 28], "proc": [6, 15], "proc_dir": [8, 11], "procedur": [2, 23, 26, 27], "process": [1, 2, 4, 5, 6, 8, 11, 14, 16, 21, 22, 25, 26, 28], "prod_": 6, "prod_i": 6, "produc": 11, "product": 2, "program": [1, 2, 4, 6, 9, 11, 12, 14, 19, 21, 22, 24, 25, 26, 27, 28], "progress": 20, "project": [0, 15], "propos": 1, "provid": [8, 9, 10, 11, 12, 14, 19, 23, 29], "pseudo": [6, 8, 14, 22, 25, 28], "public": 15, "publish": 15, "put": 20, "py": [19, 20, 21, 22, 25, 26, 27, 28, 29], "pypi": 19, "python": [19, 20], "python3": [1, 2, 4, 5, 6, 19, 20, 21, 22, 25, 26, 27, 28, 29], "q": [2, 20], "quad": 17, "quadrat": 17, "question": 7, "quick": 1, "quiet": 20, "quot": 20, "r": [1, 5, 6, 15, 20, 21, 28], "radiu": 20, "rai": [14, 19], "rais": 29, "random": [1, 8, 14, 21, 22, 25, 27, 28], "random_max_num_prob": [1, 21], "randomli": [2, 5, 6], "rang": [6, 21, 25, 27], "rangle_": 6, "rangle_i": 6, "rangle_n": 6, "rank": [8, 11, 16, 22, 25, 26, 28], "ratio": [2, 6, 28], "re": [21, 25, 27], "reach": 27, "read": [1, 4, 8, 11, 12, 16], "receiv": 29, "recommend": [2, 5, 19], "record": [14, 22], "ref": 25, "refer": [9, 11, 15, 29], "reflect": [14, 15], "refrect": 19, "regard": 9, "region": [22, 23, 26, 28], "rel": [9, 14], "relat": [2, 6, 13, 14], "remain": [2, 6], "reorgan": 22, "repeat": [1, 2, 5], "replac": [2, 7], "replica": [3, 6, 13, 14, 15, 23, 28], "report": [7, 15], "repres": [6, 9, 11, 28], "reproduc": 1, "request": [22, 28], "requir": [4, 11, 19, 20], "res_t": [22, 28], "res_t0": 22, "resampl": 6, "resampling_interv": 6, "research": 7, "reserv": 15, "reset": 6, "resetrand": 8, "resolv": 7, "respect": [1, 2, 4, 6, 16, 21, 22, 25, 27, 28], "result": [1, 3, 5, 8, 9, 11, 12, 14, 15, 21, 22, 28], "result_fx": 28, "result_t": [22, 28], "result_t0": 22, "result_txxx": 28, "resum": [1, 2, 4, 6, 8, 14, 16], "retrain": 1, "return": [1, 2, 6, 8, 9, 11, 29], "rev": [6, 15], "review": 15, "reweight": 6, "rewrit": 19, "rewritten": 6, "rheed": 14, "right": [2, 6, 14, 15, 17, 21, 28], "rnd": 8, "rng": 8, "root": [8, 9, 11, 14, 21, 22, 28], "root_dir": [8, 9, 11, 14], "rosenbrock": 17, "rou": 15, "run": [1, 2, 6, 8, 11, 13, 16, 21, 22, 23, 26, 27, 28, 29], "run_mod": [1, 2, 4, 6, 8], "runner": [8, 11, 12, 13, 21, 22, 23, 25, 26, 27, 28], "runtimeerror": 29, "rxmc": [2, 22], "s0010465522001849": 15, "sai": 2, "same": [1, 2, 4, 6, 9, 19, 21, 22, 25, 26, 28], "sampl": [1, 2, 4, 19, 23], "satisfi": [2, 9, 25], "save": 14, "scale": [5, 20], "scatter": 22, "scheme": 6, "scienc": [0, 15], "sciencedirect": 15, "scipi": [5, 19], "score": [1, 21], "script": [19, 20, 21, 22, 25, 26, 27, 28, 29], "se": [0, 1, 2, 3, 5, 7, 9, 10, 12, 14, 20, 21, 22, 23, 24, 28, 29], "search": [1, 2, 5, 6, 8, 9, 11, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 27, 28, 29], "second": [1, 2, 4, 5, 6, 14, 16, 21, 22, 25, 26, 27, 28], "section": [3, 8, 9, 13, 16, 17, 21, 22, 23, 25, 26, 27, 28, 29], "see": [2, 5, 6, 8, 9, 14, 15, 16, 19, 21, 22, 25, 26, 27, 28, 29], "seed": [8, 14, 21, 22, 25, 26, 27, 28, 29], "seed_delta": 14, "seen": [21, 26, 27, 28], "selct": 5, "select": [1, 23], "self": [8, 9, 11, 29], "selfloop": 20, "send": 7, "separ": [14, 19], "sequenc": [6, 21], "seri": [2, 6, 15], "serial": 16, "set": [1, 4, 5, 8, 9, 11, 12, 14, 16, 21, 22, 25, 26, 27, 28, 29], "set_funct": 29, "sever": [2, 5], "sh": [21, 22, 25, 26, 27, 28], "shape": 29, "shift": 5, "shorthand": 14, "should": [1, 2, 4, 5, 6, 8, 9, 11, 14, 21], "show": [20, 25, 27], "shown": [1, 2, 4, 6, 19, 21, 26], "sim": [2, 14], "simpl": [2, 5, 23], "simplex": [5, 27], "simplexdata": 27, "simul": 2, "sinc": [2, 15, 16, 26, 27], "sixth": [6, 28], "skip": [22, 29], "slightli": 2, "small": [22, 26, 28], "smaller": [1, 2], "so": [1, 5, 6, 21, 22, 28, 29], "soc": 15, "softwar": [0, 15, 19, 25, 26, 27], "solid": [0, 15], "solut": [1, 2, 5, 14, 15, 21, 29], "solv": [2, 10, 12, 15, 23, 27], "solver": [0, 1, 2, 3, 4, 5, 6, 9, 12, 13, 15, 16, 19, 21, 22, 23, 24, 25, 26, 27, 28], "solverbas": [11, 12], "some": [1, 2, 6, 9], "somorjai": 15, "sourc": [19, 29], "space": [1, 2, 3, 4, 5, 6, 8, 9, 14, 20, 22, 25, 26, 28], "specif": [9, 26, 27], "specifi": [1, 2, 4, 6, 7, 8, 9, 11, 14, 16, 17, 20, 21, 22, 25, 26, 27, 28], "split": [2, 6, 20], "sqrt": 17, "src": [19, 20, 21, 22, 25, 26, 27, 28, 29], "stabl": 5, "stand": 28, "standard": [6, 15, 21, 26, 27, 28], "stark": 15, "start": [1, 2, 4, 6, 8, 16, 27], "state": [0, 1, 2, 4, 6, 8, 14, 15, 16], "statist": [6, 15, 28], "statu": 14, "steepest": 5, "step": [1, 2, 5, 8, 11, 14, 21, 22, 25, 27, 28], "step_list": [2, 6, 22, 28], "still": 5, "stochast": 2, "store": [1, 2, 4, 6, 8, 11, 14, 16, 26, 27, 28], "store_fil": 8, "str": [8, 9, 11, 19], "string": [1, 2, 4, 6, 8, 14, 17], "string_list": [1, 4, 5], "stronger": 2, "structur": [15, 19], "stuck": 2, "studi": 2, "sub": [9, 25], "subclass": 8, "subfold": [16, 25], "submit": [8, 9, 16], "subsect": [2, 5, 6, 8, 14, 21, 22, 28], "subsequ": [1, 2, 4, 5, 6, 22, 25, 28], "substitut": 2, "success": [2, 6], "successfulli": 27, "suffici": 14, "suffix": 14, "suggest": [2, 6], "sugiyama": 15, "suit": 2, "suitabl": 1, "sum": [5, 6], "sum_": [2, 17], "sum_k": 6, "sumitani": 15, "summat": 2, "super": [8, 11], "support": [0, 4, 5, 15], "surfac": [14, 15, 19], "swendsen": 15, "sxrd": [14, 15, 19], "sy": 12, "symbol": 28, "symmetri": 2, "system": [2, 7], "systemat": 5, "t": [1, 2, 6, 15, 21, 22, 25, 28], "t_": 6, "t_0": 6, "t_1": 6, "t_2": 6, "t_i": 6, "t_n": 6, "tajiri": 15, "takahashi": 15, "take": [1, 2, 4, 8, 9, 11, 21, 22, 25, 26, 27, 28], "taken": [1, 2, 6, 8, 9, 11, 16, 23, 27], "takeo": 15, "tamura": 15, "tanaka": 15, "tee": [21, 22, 25, 26, 27, 28], "temper": 2, "temperatur": [2, 6, 22, 25, 28], "tend": 22, "terayama": 15, "termin": [14, 27], "test": [14, 25, 29], "text": 6, "th": [6, 11, 21], "than": [2, 5, 14, 20, 22, 25, 28], "thank": [0, 7], "thei": [9, 16, 22, 27], "them": [1, 8, 9, 10], "therefor": 6, "thi": [1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 14, 15, 20, 21, 22, 25, 26, 27, 28, 29], "third": [2, 6, 16, 21, 22, 25, 26, 28], "thompson": 1, "those": [1, 21, 22, 26, 28], "thread": 11, "three": [8, 14], "through": [6, 9], "thu": 1, "tild": 6, "time": [1, 2, 4, 5, 6, 8, 9, 14, 19, 21, 22, 25, 26, 27, 28], "timer": 8, "titl": 15, "tlogspac": [2, 6, 22, 25, 28], "tmax": [2, 6, 22, 25, 28], "tmin": [2, 6, 22, 25, 28], "tnum": [6, 28], "tokyo": [0, 7, 15], "toml": [9, 12, 14, 19, 21, 22, 25, 26, 27, 28, 29], "tomli": 19, "too": 2, "tool": [2, 6, 13, 15, 27], "top": [21, 26, 27], "total": [14, 15, 16, 19], "tottori": 15, "tqdm": 20, "train": 1, "transfer": [6, 8], "transform": 9, "transis": 2, "transit": [2, 6], "translat": 14, "trap": 5, "treat": [2, 9, 11], "trhepd": [14, 15, 19], "trial": [22, 25, 28], "trial_txxx": 28, "trivial": [4, 9], "true": [2, 6, 9, 16, 22, 25, 28], "tsuda": 15, "tsukamoto": 0, "tune": 2, "tupl": [9, 11], "turn": 6, "tutori": [0, 13, 21, 22, 24, 25, 26, 27, 28], "two": [2, 4, 6, 8, 11, 15, 19, 22, 24, 25, 26, 27, 28], "txt": [20, 21, 22, 25, 26, 27, 28], "type": [11, 14, 19, 26], "u": [1, 2, 7, 15, 19, 20], "ueno": 15, "uncertainti": 2, "under": [6, 15, 16, 20, 21, 22, 25, 26, 27, 28], "unfortun": [2, 6], "uniformli": [5, 22, 28], "uninstal": 13, "uninterrupt": 1, "unit": [5, 8, 14, 20], "unit1": 20, "unit2": 20, "unit_list": [5, 22, 25, 28], "uniti": 6, "univers": [0, 15], "updat": [1, 2, 6, 14, 19, 22, 25, 28], "upper": [8, 22, 25, 28], "url": 15, "us": [1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 14, 15, 17, 19, 21, 22, 23, 24, 25, 26, 27, 28, 29], "usabl": [0, 15], "usag": [10, 13, 23], "user": [2, 9, 13, 15, 19, 29], "usual": [2, 11], "util": [2, 6], "v0": 15, "v1": 15, "v2": 15, "v3": 15, "vallei": 2, "valu": [1, 2, 4, 5, 6, 8, 9, 11, 14, 17, 20, 21, 22, 24, 25, 26, 27, 28], "value_01": 21, "value_02": 21, "van": 15, "variabl": [1, 2, 4, 5, 6, 8, 9, 11, 24, 25, 27], "varianc": 6, "variou": 14, "vec": [1, 2, 17], "vector": [9, 11, 14, 25], "verifi": 2, "version": [2, 7, 9, 11, 13, 14, 19, 25], "vertic": [25, 28], "via": 20, "voeg": 15, "volum": 15, "w": [2, 6, 15], "w_n": 6, "wa": [0, 14, 15, 22, 28], "wai": [2, 29], "walker": [2, 6, 8, 22, 25, 28], "wander": 15, "wang": 15, "want": [14, 19, 21, 22, 26, 27, 28], "we": [0, 1, 2, 6, 15, 21, 22, 25, 26, 27, 28, 29], "weight": [2, 6, 28], "well": 1, "what": [13, 21], "when": [1, 2, 5, 6, 7, 8, 9, 11, 14, 15, 16, 19, 20, 22, 25, 26, 28], "where": [1, 2, 6, 9, 14, 20, 21, 22, 25, 26, 27, 28], "whether": [2, 6, 9, 14], "which": [2, 6, 9, 11, 14, 21, 22, 25, 26, 28], "while": [1, 22], "whitespac": 20, "whole": [2, 9, 20, 27], "why": 2, "wil": 23, "within": [25, 26], "without": [1, 6, 19], "work": [8, 11], "work_dir": 9, "wors": 6, "would": 19, "wrapper": 15, "write": 8, "write_input": 14, "write_result": 14, "written": [9, 11, 14, 21, 22, 25, 26, 27], "www": 15, "x": [1, 2, 3, 4, 6, 8, 9, 11, 14, 15, 17, 18, 19, 21, 22, 24, 25, 28, 29], "x1": [6, 21, 22, 25, 26, 27, 28, 29], "x1_action": 21, "x2": [21, 22, 25, 26, 27, 28, 29], "x2_action": 21, "x_": [6, 17, 25], "x_0": 6, "x_1": 6, "x_2": 6, "x_i": [6, 17], "x_n": 6, "x_t": 2, "xa": 6, "xatol": 5, "xcol": [21, 22, 27], "xxx": 28, "y": [6, 9, 14, 15, 17, 24, 29], "ycol": [21, 22, 27], "year": 15, "yield": 21, "yoshimi": 15, "you": [1, 4, 5, 7, 14, 15, 19, 20, 21, 22, 25, 26, 27, 28, 29], "your": [7, 12], "yourself": 19, "yuichi": 15, "z": [6, 28], "z0": [6, 28], "z1": [1, 2, 5, 6], "z1_action": 1, "z2": [1, 2, 5, 6], "z2_action": 1, "z3": 5, "z_0": [6, 28], "z_n": [6, 28], "zero": 14, "zhang": 15, "\u03b2": 6}, "titles": ["Acknowledgements", "Bayesian optimization bayes", "Replica exchange Monte Carlo exchange", "Search algorithms", "Direct parallel search mapper", "Nelder-Mead method minsearch", "Population Annealing Monte Carlo pamc", "Contact", "Algorithm", "Commons", "(For developers) User-defined algorithms and solvers", "Solver", "Usage", "Welcome to ODAT-SE documentation!", "Input file", "Introduction", "Output files", "analytical solver", "Direct Problem Solver", "Installation of ODAT-SE", "Related Tools", "Optimization by Bayesian Optimization", "Optimization by replica exchange Monte Carlo", "Tutorials", "Minimization of an analytical function", "Replica Exchange Monte Carlo search with limitation", "Grid search", "Optimization by Nelder-Mead method", "Optimization by population annealing", "Adding a direct problem solver"], "titleterms": {"1": 6, "2": 6, "For": 10, "about": 6, "acknowledg": 0, "ad": 29, "add": 29, "affin": 9, "ai": 6, "algorithm": [1, 2, 3, 6, 8, 10, 14], "algorithmbas": 8, "an": 24, "analyt": [17, 24, 29], "anneal": [6, 28], "base": [9, 14], "bay": 1, "bayesdata": 1, "bayesian": [1, 21], "benchmark": 29, "best_result": [2, 6], "calcul": [21, 22, 25, 26, 27, 28], "carlo": [2, 6, 22, 25], "chain": 2, "class": 8, "colormap": 4, "common": [9, 16], "contact": 7, "content": 13, "defin": 10, "definit": [1, 2, 4, 6, 8], "descript": 1, "develop": [10, 15], "direct": [4, 18, 29], "document": 13, "domain": 8, "download": 19, "exchang": [2, 22, 25], "execut": [26, 27], "file": [1, 2, 4, 5, 6, 14, 16, 21, 22, 25, 26, 27, 28], "function": 24, "fx": 6, "goal": 6, "grid": 26, "how": [19, 29], "i": 15, "import": 6, "inequ": 9, "info": 9, "inform": 15, "input": [1, 2, 4, 5, 6, 14, 17, 21, 22, 25, 26, 27, 28], "instal": 19, "introduct": 15, "item": 9, "licens": 15, "limit": [9, 14, 25], "list": [2, 6], "locat": [25, 26, 27], "log": [14, 16], "main": 15, "map": [9, 14], "mapper": 4, "markov": 2, "mead": [5, 27], "mesh": [1, 2, 4, 6], "meshgrid": 8, "method": [5, 27], "minim": [5, 24], "minsearch": 5, "mont": [2, 6, 22, 25], "neighborhood": [2, 6], "nelder": [5, 27], "number": 6, "odat": [13, 15, 19], "odats": 9, "odatse_neighborlist": 20, "optim": [1, 21, 22, 27, 28], "output": [1, 2, 4, 5, 6, 16], "pa": 6, "pamc": 6, "parallel": 4, "param": [1, 2, 4, 5, 6], "paramet": [1, 2, 4, 5, 6, 17], "pickl": 16, "popul": [6, 28], "prepar": [1, 2, 4, 5, 6], "prerequisit": 19, "problem": [18, 29], "rank": [2, 6], "re": 5, "refer": [1, 2, 6], "refernc": 4, "region": 8, "relat": 20, "replica": [2, 22, 25], "restart": [1, 2, 4, 5, 6], "result": [2, 6, 25, 26, 27], "result_t": [2, 6], "run": 19, "runner": [9, 14, 16], "sampl": [6, 21, 22, 25, 26, 27, 28], "se": [13, 15, 19], "search": [3, 4, 25, 26], "section": [1, 4, 5, 14], "simplexdata": 5, "solver": [10, 11, 14, 17, 18, 29], "statu": 16, "step": 6, "time": 16, "tool": 20, "trial": [2, 6], "trial_t": 6, "trivialmap": 9, "tutori": 23, "txt": [1, 2, 4, 5, 6], "uninstal": 19, "unlimit": 9, "usag": [12, 20], "user": 10, "version": 15, "visual": [21, 22, 25, 26, 27, 28], "welcom": 13, "what": 15}}) \ No newline at end of file diff --git a/manual/v3.0.0/en/solver/analytical.html b/manual/v3.0.0/en/solver/analytical.html new file mode 100644 index 00000000..9966ff61 --- /dev/null +++ b/manual/v3.0.0/en/solver/analytical.html @@ -0,0 +1,113 @@ + + + + + + + + analytical solver — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

analytical solver

+

analytical is a Solver that computes a predefined benchmark function \(f(x)\) for evaluating the performance of search algorithms.

+
+

Input parameters

+

The funtion_name parameter in the solver section specifies the function to use.

+
    +

  • function_name

    +

    Format: string

    +

    Description: Function name. The following functions are available.

    +
      +

    • quadratics

      +
        +

      • Quadratic function

        +
        +\[f(\vec{x}) = \sum_{i=1}^N x_i^2\]
        +
        • +

      • The optimized value \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • rosenbrock

      + +
      +\[f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right]\]
      +
        +

      • The optimized value \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)\)

        • +
      +
      • +

    • ackley

      + +
      +\[f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right]\]
      +
        +

      • The optimized value \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • himmerblau

      + +
      +\[f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2\]
      +
        +

      • The optimized value \(f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0\)

        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/solver/index.html b/manual/v3.0.0/en/solver/index.html new file mode 100644 index 00000000..fb34cb2c --- /dev/null +++ b/manual/v3.0.0/en/solver/index.html @@ -0,0 +1,67 @@ + + + + + + + + Direct Problem Solver — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Direct Problem Solver

+

Direct problem solver Solver calculates the function to be optimized \(f(x)\) at the search parameter \(x\).

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/start.html b/manual/v3.0.0/en/start.html new file mode 100644 index 00000000..afa08ca4 --- /dev/null +++ b/manual/v3.0.0/en/start.html @@ -0,0 +1,159 @@ + + + + + + + + Installation of ODAT-SE — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Installation of ODAT-SE

+
+

Prerequisites

+
    +

  • Python3 (>=3.9)

    +
    +
      +
    • +
      The following Python packages are required.
        +

      • tomli >= 1.2

        • +

      • numpy >= 1.14

        • +
      +
      +
      +
      • +

    • Optional packages

      +
      +
        +

      • mpi4py (required for grid search)

        • +

      • scipy (required for Nelder-Mead method)

        • +

      • physbo (>=2.0, required for Baysian optimization)

        • +
      +
      +
      • +
    +
    +
    • +
+
+
+

How to download and install

+

You can install the ODAT-SE python package and the odatse command following the instructions shown below.

+
    +

  • Installation using PyPI (recommended)

    +
    +
      +

    • python3 -m pip install ODAT-SE

      +
      +
        +

      • --user option to install locally ($HOME/.local)

        • +

      • If you use ODAT-SE[all], optional packages will be installed at the same time.

        • +
      +
      +
      • +
    +
    +
    • +

  • Installation from source code

    +
    +
      +

    1. git clone https://github.com/issp-center-dev/ODAT-SE

      2. +

    2. python3 -m pip install ./ODAT-SE

      +
      +
        +

      • The pip version must be 19 or higher (can be updated with python3 -m pip install -U pip).

        • +
      +
      +
      3. +
    +
    +
    • +

  • Download the sample files

    +
    +
      +

    • Sample files are included in the source code.

      • +

    • git clone https://github.com/issp-center-dev/ODAT-SE

      • +
    +
    +
    • +
+
+
+

How to run

+

In ODAT-SE, the analysis is carried out by using a predefined optimization algorithm Algorithm and a direct problem solver Solver.

+
$ odatse input.toml
+
+
+

See Search algorithms for the predefined Algorithm and Direct Problem Solver for the Solver.

+

The direct problem solvers for analyses of experimental data of two-dimensional material structure are provided as separate modules. +To perform these analyses, you need to install the modules and the required software packages. +At present, the following modules are provided:

+
    +

  • odatse-STR module for Total Refrection High-energy Positron Diffraction (TRHEPD)

    • +

  • odatse-SXRD module for Surface X-ray Diffraction (SXRD)

    • +

  • odatse-LEED module for Low-energy Electron Diffraction (LEED)

    • +
+

If you want to prepare the Algorithm or Solver by yourself, use the ODAT-SE package. +See (For developers) User-defined algorithms and solvers for details.

+

The program can be executed without installing odatse command; instead, run src/odatse_main.py script directly as follows. It would be convenient when you are rewriting programs.

+
$ python3 src/odatse_main.py input
+
+
+
+
+

How to uninstall

+

Please type the following command:

+
$ python3 -m pip uninstall ODAT-SE
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tool.html b/manual/v3.0.0/en/tool.html new file mode 100644 index 00000000..66f21705 --- /dev/null +++ b/manual/v3.0.0/en/tool.html @@ -0,0 +1,125 @@ + + + + + + + + Related Tools — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + + + + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/bayes.html b/manual/v3.0.0/en/tutorial/bayes.html new file mode 100644 index 00000000..8fa0db8f --- /dev/null +++ b/manual/v3.0.0/en/tutorial/bayes.html @@ -0,0 +1,195 @@ + + + + + + + + Optimization by Bayesian Optimization — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Optimization by Bayesian Optimization

+

This tutorial describes how to estimate the minimization problem of Himmelblau function by using Bayesian optimization (BO). +ODAT-SE uses PHYSBO for BO. +PHYSBO package should be installed beforehand.

+
+

Sample files

+

Sample files are available from sample/analytical/bayes . +This directory includes the following files:

+
    +

  • input.toml

    +

    The input file of odatse

    +
    • +

  • do.sh

    +

    Script files for running this tutorial

    +
    • +
+

In addition, plot_himmel.py in sample directory is used to visualize the result.

+
+
+

Input files

+

This subsection describes the input file. +For details, see the manual of bayes.

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[algorithm]
+name = "bayes"
+seed = 12345
+
+[algorithm.param]
+min_list = [-6.0, -6.0]
+max_list = [ 6.0,  6.0]
+num_list = [61, 61]
+
+[algorithm.bayes]
+random_max_num_probes = 20
+bayes_max_num_probes = 40
+
+
+

The contents of [base], [solver], and [runner] sections are the same as those for the search by the Nelder-Mead method (minsearch).

+

[algorithm] section specifies the algorithm to use and its settings.

+
    +

  • name is the name of the algorithm you want to use, and in this tutorial we will do a Bayesian optimization analysis, so specify bayes.

    • +

  • seed specifies the initial input of random number generator.

    • +
+

[algorithm.param] section specifies the range of parameters to search and their initial values.

+
    +

  • min_list and max_list specify the minimum and maximum values of the search grid, respectively.

    • +

  • num_list specifies the number of grid points along each parameter.

    • +
+

[algorithm.bayes] section sets the parameters for Bayesian optimization.

+
    +

  • random_max_num_probes specifies the number of random searches before Bayesian optimization.

    • +

  • bayes_max_num_probes specifies the number of Bayesian searches.

    • +
+

For details on other parameters that can be specified in the input file, see the chapter on input files of bayes.

+
+
+

Calculation

+

First, move to the folder where the sample file is located. (Hereinafter, it is assumed that you are the root directory of ODAT-SE.)

+
$ cd sample/analytical/bayes
+
+
+

Then, run the main program. It will take a few secondes on a normal PC.

+
$ python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

By executing the program, a directory with the name 0 is created under output directory, and the results are written in it. +The following standard output will be shown:

+
# parameter
+random_max_num_probes = 10
+bayes_max_num_probes = 20
+score = TS
+interval = 5
+num_rand_basis = 5000
+value_01 =  5.10000
+value_02 =  4.90000
+R-factor = 0.037237314010261195
+0001-th step: f(x) = -0.037237 (action=150)
+   current best f(x) = -0.037237 (best action=150)
+
+value_01 =  4.30000
+value_02 =  3.50000
+...
+
+
+

A list of hyperparameters, followed by candidate parameters at each step and the corresponding function values are shown first. +It also outputs the grid index (action) and f(x) of the best value at that time. +The final estimated parameters are output to output/BayesData.txt.

+

In this case, BayesData.txt can be seen as the following

+
 #step x1 x2 fx x1_action x2_action fx_action
+ 0 -2.4 -0.7999999999999998 113.2192 -2.4 -0.7999999999999998 113.2192
+ 1 -2.4 -0.7999999999999998 113.2192 1.6000000000000005 4.600000000000001 263.12320000000045
+ 2 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.8000000000000007 -0.39999999999999947 28.995199999999958
+ 3 2.8000000000000007 -0.39999999999999947 28.995199999999958 4.800000000000001 5.800000000000001 1306.739200000001
+ 4 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.3999999999999995 2.5999999999999996 44.16320000000003
+ 5 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.200000000000001 -5.2 623.6672
+
+ 6 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.1999999999999993 2.200000000000001 65.45919999999997
+ 7 4.200000000000001 -1.7999999999999998 23.619200000000067 4.200000000000001 -1.7999999999999998 23.619200000000067
+ 8 4.200000000000001 -1.7999999999999998 23.619200000000067 -2.5999999999999996 -0.1999999999999993 111.10720000000002
+ 9 4.200000000000001 -1.7999999999999998 23.619200000000067 0.6000000000000005 0.8000000000000007 130.00319999999994
+ 10 4.200000000000001 -1.7999999999999998 23.619200000000067 -0.5999999999999996 -0.5999999999999996 178.7552
+ ...
+ 38 3.200000000000001 1.8000000000000007 1.3952000000000133 3.200000000000001 -1.3999999999999995 8.051199999999973
+ 39 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.8 -3.0 3.433599999999999
+ 40 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.0 -2.8 27.705600000000004
+ 41 3.6000000000000014 -1.7999999999999998 0.051200000000003215 3.6000000000000014 -1.7999999999999998 0.051200000000003215
+ 42 3.6000000000000014 -1.7999999999999998 0.051200000000003215 2.0 2.5999999999999996 22.457599999999996
+...
+
+
+

The first column contains the number of steps, and the second, third, and fourth columns contain x2, x2, and f(x), which give the highest score at that time. +This is followed by the candidate x1, x2 and f(x) for that step. +In this case, you can see that the correct solution is obtained at the 41st step.

+
+
+

Visualization

+

You can see at what step the parameter gave the minimum score by looking at BayesData.txt.

+
$ python3 ../plot_himmel.py --xcol=1 --ycol=2 --format="-o" --output=output/res.pdf output/BayesData.txt
+$ python3 ../plot_himmel.py --xcol=4 --ycol=5 --format="o" --output=output/actions.pdf output/BayesData.txt
+
+
+

By executing the above commands, output/actions.pdf and output/res.pdf will be created that plots the grid points evaluated during the Bayes optimization process, and the sequence of the points that yield the least scores, respectively, on top of the contour of Himmelblau function.

+
+../_images/res_bayes_plot.png +
+

Fig. 4 The grid points evaluated during the Bayesian optimization (left) and the history of points that yield the least scores (right).

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/exchange.html b/manual/v3.0.0/en/tutorial/exchange.html new file mode 100644 index 00000000..a9f0d83d --- /dev/null +++ b/manual/v3.0.0/en/tutorial/exchange.html @@ -0,0 +1,195 @@ + + + + + + + + Optimization by replica exchange Monte Carlo — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Optimization by replica exchange Monte Carlo

+

This tutorial describes how to estimate the minimization problem of Himmelblau function by using the replica exchange Monte Carlo method (RXMC).

+
+

Sample files

+

Sample files are available from sample/analytical/exchange . +This directory includes the following files:

+
    +

  • input.toml

    +

    The input file of odatse

    +
    • +

  • do.sh

    +

    Script files for running this tutorial

    +
    • +
+
+
+

Input files

+

This subsection describes the input file. +For details, see the input file section of the manual.

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[algorithm]
+name = "exchange"
+seed = 12345
+
+[algorithm.param]
+min_list = [3.0, 3.0]
+max_list = [6.0, 6.0]
+step_list = [0.3, 0.3]
+
+[algorithm.exchange]
+Tmin = 0.01
+Tmax = 100.0
+numsteps = 10000
+numsteps_exchange = 100
+nreplica_per_proc = 20
+
+
+

In the following, we will briefly describe this input file. +For details, see the manual of Replica exchange Monte Carlo exchange.

+

The contents of [base], [solver], and [runner] sections are the same as those for the search by the Nelder-Mead method (minsearch).

+

[algorithm] section specifies the algorithm to use and its settings.

+
    +

  • name is the name of the algorithm you want to use. In this tutorial we will use RXMC, so specify exchange.

    • +

  • seed is the seed that a pseudo-random number generator uses.

    • +
+

[algorithm.param] section sets the parameter space to be explored.

+
    +

  • min_list is a lower bound and max_list is an upper bound.

    • +

  • unit_list is step length in one Monte Carlo update (deviation of Gaussian distribution).

    • +
+

[algorithm.exchange] section sets the hyper parameters for RXMC.

+
    +

  • numstep is the number of Monte Carlo steps.

    • +

  • numsteps_exchange is the number of steps between temperature exchanges.

    • +

  • Tmin, Tmax are the minimum and the maximum of temperature, respectively.

    • +

  • When Tlogspace is true, the temperature points are distributed uniformly in the logarithmic space.

    • +

  • nreplica_per_proc specifies the number of replicas that one MPI process handles.

    • +
+
+
+

Calculation

+

First, move to the folder where the sample file is located. (Hereinafter, it is assumed that you are the root directory of ODAT-SE.)

+
$ cd sample/analytical/exchange
+
+
+

Then, run the main program. It will take a few secondes on a normal PC.

+
$ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

Here, the calculation is performed using MPI parallel with 4 processes. +If you are using Open MPI and you request more processes than the number of cores, you need to add the --oversubscribe option to the mpiexec command.

+

When executed, a folder for each MPI rank will be created under output directory, and a trial.txt file containing the parameters evaluated in each Monte Carlo step and the value of the objective function, and a result.txt file containing the parameters actually adopted will be created.

+

These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters.

+
# step walker T fx x1 x2
+0 0 0.01 170.0 0.0 0.0
+0 1 0.01123654800138751 187.94429125133564 5.155393113805774 -2.203493345018569
+0 2 0.012626001098748564 3.179380982615041 -3.7929742598748666 -3.5452766573635235
+0 3 0.014187266741165962 108.25464277273859 0.8127003489802398 1.1465364357510186
+0 4 0.01594159037455999 483.84183395038843 5.57417423682746 1.8381251624588506
+0 5 0.01791284454622004 0.43633134370869153 2.9868796504069426 1.8428384502208246
+0 6 0.020127853758499396 719.7992581349758 2.972577711255287 5.535680832873856
+0 7 0.022616759492228647 452.4691017123836 -5.899340424701358 -4.722667479627368
+0 8 0.025413430367026365 45.5355817998709 -2.4155554347674215 1.8769341969872393
+0 9 0.028555923019901074 330.7972369561986 3.717750630491217 4.466110964691396
+0 10 0.032086999973704504 552.0479484091458 5.575771168463163 2.684224163039442
+...
+
+
+

best_result.txt is filled with information about the parameter with the optimal objective function, the rank from which it was obtained, and the Monte Carlo step.

+
nprocs = 80
+rank = 3
+step = 8025
+walker = 17
+fx = 3.358076734724385e-06
+x1 = 2.9998063442504126
+x2 = 1.999754886043102
+
+
+

In ODAT-SE, one replica holds samples at different temperatures because of the temperature exchanges. The result.txt in each rank folder records the data sampled by each replica. +The data reorganized for each temperature point is written to output/result_T%.txt, where % is the index of the temperature point. +The first column is the step, the second column is the rank, the third column is the value of the objective function, and the fourth and subsequent columns are the parameters. +Example:

+
# T = 0.014187266741165962
+0 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+1 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+2 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+3 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+4 3 93.5034551820852 1.3377081691728905 0.8736706475438123
+5 3 81.40963740872147 1.4541906604820898 1.0420053981467825
+...
+
+
+
+
+

Visualization

+

By plotting output/result_T%.txt, you can estimate regions where the parameters with small function values are located. +By executing the following command, the figures of two-dimensional plot res_T%.png will be generated.

+
$ python3 ../plot_himmel.py --xcol=3 --ycol=4 --skip=20 --format="o" --output=output/res_T0.png output/result_T0.txt
+
+
+

Looking at the resulting diagram, we can see that the samples are concentrated near the minima of f(x). By changing the index of the temperature, the sampling points scatters over the region at high temperature, while they tend to concentrate on the minima at low temperature.

+
+../_images/res_exchange.png +
+

Fig. 5 Distribution of sampling points on two-dimensional parameter space at \(T=\{35.02, 3.40, 0.33, 0.01\}\).

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/index.html b/manual/v3.0.0/en/tutorial/index.html new file mode 100644 index 00000000..9f8a9064 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/index.html @@ -0,0 +1,104 @@ + + + + + + + + Tutorials — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Tutorials

+

In these tutorials, how to perform inverse problem analyses using ODAT-SE is explained by examples taken from minimization of analytical functions. +In ODAT-SE, the algorithms for solving the inverse problem can be selected from the following algorithms:

+
    +

  • minsearch

    +
    +

    Nealder-Mead method.

    +
    +
    • +

  • mapper_mpi

    +
    +

    Entire search over a grid for a given parameter.

    +
    +
    • +

  • bayes

    +
    +

    Bayesian optimization.

    +
    +
    • +

  • exchange

    +
    +

    Sampling by the replica exchange Monte Carlo method.

    +
    +
    • +

  • pamc

    +
    +

    Sampling by the population annealing Monte Carlo method.

    +
    +
    • +
+

In the following sections, the procedures to run these algorithms are provided. +In addition, the usage of [runner.limitation] to apply limitations to the search region will be described. In the end of the section, how to define a direct problem solver wil be explained by a simple example.

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/intro.html b/manual/v3.0.0/en/tutorial/intro.html new file mode 100644 index 00000000..a4d95db1 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/intro.html @@ -0,0 +1,73 @@ + + + + + + + + Minimization of an analytical function — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Minimization of an analytical function

+

As an example of direct problem solver, the minimization of Himmelblau function among the Analytical solver included in ODAT-SE will be discussed in these tutorials. +The Himmelblau function is a two-variable function given as follows, having multiple number of minima. It is used as a benchmark for the evaluation of optimization algorithms.

+
+\[f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2\]
+

The minimum value \(f(x,y)=0\) is given at \((x,y)\) that equals to \((3.0, 2.0)\), \((-2.805118, 3.131312)\), \((-3.779310, -3.283186)\), and \((3.584428, -1.848126)\).

+
+../_images/plot_himmelblau.png +
+

Fig. 1 The plot of Himmelblau function.

+
+
+

[1] D. Himmelblau, Applied Nonlinear Programming, McGraw-Hill, 1972.

+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/limitation.html b/manual/v3.0.0/en/tutorial/limitation.html new file mode 100644 index 00000000..1da91343 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/limitation.html @@ -0,0 +1,216 @@ + + + + + + + + Replica Exchange Monte Carlo search with limitation — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Replica Exchange Monte Carlo search with limitation

+

This tutorial describes the constraint expression function that can be set in the [runner.limitation] section. +As an example, the replica exchange Monte Carlo method is applied to the minimization problem of Himmelblau function with constraints.

+
+

Sample files location

+

Sample files are available in the sample/analytical/limitation directory. +This directory contains the following files.

+
    +

  • input.toml

    +

    Input file for the main program.

    +
    • +

  • ref.txt

    +

    File to check if the calculation is executed correctly (answer to obtain by performing this tutorial).

    +
    • +

  • do.sh

    +

    Script prepared to calculate this tutorial at once.

    +
    • +
+

In the following, we will explain these files, and then introduce the actual calculation results.

+
+
+

Input files

+

The following input.toml is an input file for the main program.

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "exchange"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+unit_list = [0.3, 0.3]
+
+[algorithm.exchange]
+Tmin = 1.0
+Tmax = 100000.0
+numsteps = 10000
+numsteps_exchange = 100
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.limitation]
+co_a = [[1, -1],[1, 1]]
+co_b = [[0], [-1]]
+
+
+

[base] section is the parameter of the main program.

+
    +

  • dimension is the number of variables to be optimized, and in this case, it is 2.

    • +

  • output is the name of directory for the output files.

    • +
+

[algorithm] section is the section to set the search algorithm.

+
    +

  • name is the name of the search algorithm. In this case, specify "exchange" for the replica exchange Monte Carlo method.

    • +

  • seed is the seed given to the pseudo-random number generator.

    • +
+

[algorithm.param] sub-section specifies the range of parameters to be optimized.

+
    +

  • min_list and max_list specifies the lower bound and upper bound of the parameter space, respectively.

    • +

  • unit_list is step length in one MC update (deviation of Gaussian distribution).

    • +
+

[algorithm.exchange] sub-section specifies the hyperparameters of the replica exchange Monte Carlo method.

+
    +

  • numstep is the number of Monte Carlo updates.

    • +

  • numsteps_exchange specifies the number of times to attempt temperature exchange.

    • +

  • Tmin and Tmax are the lower and upper limits of the temperature, respectively.

    • +

  • If Tlogspace is true, the temperature is divided equally in log space. This option is not specified in this input.toml because the default value is true.

    • +
+

[solver] section specifies the solver used internally in the main program. +In this case, the analytical solver is specified. +The analytical solver takes an extra parameter function_name that specifies the name of the function. In this case, the Himmelblau function is specified.

+

[runner] section has a sub-section [runner.limitation], and in this section, the constraint expression is set. +In the current version, the constraint expression is defined as \(Ax+b>0\) where \(x\) is \(N\) dimensional input parameter, \(A\) is a \(M \times N\) matrix, and \(b\) is a \(M\) dimensional vector. +\(A\) and \(b\) are set by co_a and co_b, respectively. +For details, see the [limitation] section in the input file in the manual.

+

In this case, the following constraint is imposed:

+
+\[\begin{split}x_{1} - x_{2} > 0 \\ +x_{1} + x_{2} - 1 > 0\end{split}\]
+
+
+

Calculation

+

First, move to the folder where the sample file is located. (It is assumed that you are directly under the directory where you downloaded this software.)

+
$ cd sample/analytical/limitation
+
+
+

Then, execute the main program as follows. The calculation will end in about 20 seconds on a normal PC.

+
$ mpiexec -np 10 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

In this case, a calculation with 10 MPI parallel processes is performed. +When using OpenMPI, if the number of processes to be used is greater than the number of available cores, add the --oversubscribe option to the mpiexec command. +After executed, the output folder is generated, and there a subfolder for each MPI rank is created.

+

Each subfolder contains the results of the calculation. +trial.txt file, which contains the parameters and objective function values evaluated at each Monte Carlo step, and result.txt file, which contains the parameters actually adopted, are created.

+

Both files have the same format, with the first two columns being the step number and the walker number within the process, the next being the temperature, the third being the value of the objective function, and the fourth and subsequent being the parameters. +The following is the beginning of the output/0/result.txt file:

+
# step walker T fx x1 x2
+0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569
+1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+
+
+

Finally, the best parameter and the rank and Monte Carlo step at which the objective function is minimized are written to output/best_result.txt.

+
nprocs = 10
+rank = 2
+step = 4523
+walker = 0
+fx = 0.00010188398524402734
+x1 = 3.584944906595298
+x2 = -1.8506985826548874
+
+
+

do.sh is available as a script to calculate all at once. +Additionally, in do.sh, the difference between best_result.txt and ref.txt is also compared.

+
#!/bin/bash
+
+mpiexec -np 10 --oversubscribe python3 ../../../src/odatse_main.py input.toml
+
+echo diff output/best_result.txt ref.txt
+res=0
+diff output/best_result.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: best_result.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

Visualization of the calculation result

+

By visualizing the result.txt file, we can confirm that the search is only for coordinates that satisfy the constraint expression. +hist2d_limitation_sample.py is prepared to visualize the 2D parameter space. +This generates a histogram of the posterior probability distribution in the <execution date>_histogram folder. +The histogram is generated using the data obtained by discarding the first 1000 steps of the search as a burn-in period.

+
$ python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1
+
+
+

The figure shows the posterior probability distribution and the two lines \(x_{1} - x_{2} = 0\), \(x_{1} + x_{2} - 1 = 0\), and it is confirmed that the search is only for the range where \(x_{1} - x_{2} > 0\), \(x_{1} + x_{2} - 1 > 0\).

+
+../_images/res_limitation.png +
+

Fig. 7 Plots of sampled parameters and probability distribution. The horizontal and vertical axes denote x1 and x2, respectively.

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/mapper.html b/manual/v3.0.0/en/tutorial/mapper.html new file mode 100644 index 00000000..01b42864 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/mapper.html @@ -0,0 +1,172 @@ + + + + + + + + Grid search — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + + + + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/minsearch.html b/manual/v3.0.0/en/tutorial/minsearch.html new file mode 100644 index 00000000..e1166895 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/minsearch.html @@ -0,0 +1,192 @@ + + + + + + + + Optimization by Nelder-Mead method — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + +
+ + +
+

Optimization by Nelder-Mead method

+

In this section, we will explain how to calculate the minimization problem of Himmelblau function using the Nelder-Mead method. +The specific calculation procedure is as follows.

+
    +

  1. Preparation of an input file

    +

    Prepare an input file that describes parameters in TOML format.

    +
    2. +

  2. Run the main program

    +

    Run the calculation using src/odatse_main.py to solve the minimization problem.

    +
    3. +
+
+

Location of the sample files

+

The sample files are located in sample/analytical/minsearch. +The following files are stored in the folder.

+
    +

  • input.toml

    +

    Input file of the main program.

    +
    • +

  • do.sh

    +

    Script prepared for doing all calculation of this tutorial

    +
    • +
+

In addition, plot_himmel.py in the sample folder is used to visualize the result.

+
+
+

Input file

+

In this section, we will prepare the input file input.toml for the main program. +The details of input.toml can be found in the input file section of the manual.

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.log]
+interval = 20
+
+[algorithm]
+name = "minsearch"
+seed = 12345
+
+[algorithm.param]
+min_list = [-6.0, -6.0]
+max_list = [ 6.0,  6.0]
+initial_list = [0, 0]
+
+
+

[base] section describes parameters used in the whole program.

+
    +

  • dimension is the number of variables to be optimized, in this case 2 since Himmelblau function is a two-variable function.

    • +

  • output_dir is the name of directory for output.

    • +
+

[solver] section specifies the solver to be used inside the main program and its settings.

+
    +

  • name is the name of the solver you want to use. In this tutorial, we perform analyses of an analytical function in the analytical solver.

    • +

  • function_name is the name of the function in the analytical solver.

    • +
+

[runner] section specifies settings on calling the direct problem solver from the inverse problem analysis algorithm.

+
    +

  • interval in [runner.log] specifies the frequency of the log output. The logs are written in every interval steps.

    • +
+

[algorithm] section specifies the algorithm to use and its settings.

+
    +

  • name is the name of the algorithm you want to use. In this tutorial we will use minsearch since we will be using the Nelder-Mead method.

    • +

  • seed specifies the initial input of random number generator.

    • +
+

[algorithm.param] section specifies the range of parameters to search and their initial values.

+
    +

  • min_list and max_list specify the minimum and maximum values of the search range, respectively.

    • +

  • initial_list specifies the initial values.

    • +
+

Other parameters, such as convergence judgments used in the Nelder-Mead method, can be done in the [algorithm] section, although they are omitted here because the default values are used. +See the input file chapter for details.

+
+
+

Calculation execution

+

First, move to the folder where the sample files are located. (We assume that you are directly under the directory where you downloaded this software.)

+
$ cd sample/analytical/minsearch
+
+
+

Then, run the main program. The computation time takes only a few seconds on a normal PC.

+
$ python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

The standard output will be seen as follows.

+
Optimization terminated successfully.
+         Current function value: 0.000000
+         Iterations: 40
+         Function evaluations: 79
+iteration: 40
+len(allvecs): 41
+step: 0
+allvecs[step]: [0. 0.]
+step: 1
+allvecs[step]: [0.375 0.375]
+step: 2
+allvecs[step]: [0.0625 0.9375]
+step: 3
+allvecs[step]: [0.65625 1.46875]
+step: 4
+allvecs[step]: [0.328125 2.859375]
+...
+
+
+

The x1 and x2 are the candidate parameters at each step and the function value at that point. +The final estimated parameters is written to output/res.dat. +In the current case, the following result will be obtained:

+
fx = 4.2278370361994904e-08
+x1 = 2.9999669562950175
+x2 = 1.9999973389336225
+
+
+

It is seen that one of the minima is obtained.

+
+
+

Visualization of calculation results

+

The steps taken during the search by the Nelder-Mead method is written in output/0/SimplexData.txt. A tool to plot the path is prepared as simplex/plot_himmel.py.

+
$ python3 ../plot_himmel.py --xcol=1 --ycol=2 --output=output/res.pdf output/0/SimplexData.txt
+
+
+

By executing the above command, output/res.pdf will be generated.

+
+../_images/res_minsearch.png +
+

Fig. 2 The path taken during the minimum search by the Nelder-Mead method is drawn by the blue line. The black curves show contour of Himmelblau function.

+
+
+

The path of the minimum search by the Nelder-Mead method is drawn on top of the contour plot of Himmelblau function. Starting from the initial value at (0, 0), the path reaches to one of the minima, (3, 2).

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/pamc.html b/manual/v3.0.0/en/tutorial/pamc.html new file mode 100644 index 00000000..43a1c7d4 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/pamc.html @@ -0,0 +1,212 @@ + + + + + + + + Optimization by population annealing — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Optimization by population annealing

+

This tutorial describes how to estimate the optimization problem of Himmelblau function by using the population annealing Monte Carlo method (PAMC).

+
+

Sample files

+

Sample files are available from sample/analytical/pamc . +This directory includes the following files:

+
    +

  • input.toml

    +

    The input file of odatse

    +
    • +

  • plot_result_2d.py

    +

    Program to visualize the results

    +
    • +

  • do.sh

    +

    Script files for running this tutorial

    +
    • +
+
+
+

Input files

+

This subsection describes the input file. +For details, see the input file section of the manual.

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.log]
+interval = 20
+
+[algorithm]
+name = "pamc"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+step_list = [0.1, 0.1]
+
+[algorithm.pamc]
+Tmin = 1.0
+Tmax = 100.0
+Tnum = 21
+Tlogspace = true
+numsteps_annealing = 100
+nreplica_per_proc = 100
+
+
+

In the following, we will briefly describe this input file. +For details, see the manual of Population Annealing Monte Carlo pamc.

+

The contents of [base], [solver], and [runner] sections are the same as those for the search by the Nelder-Mead method (minsearch).

+

[algorithm] section specifies the algorithm to use and its settings.

+
    +

  • name is the name of the algorithm you want to use In this tutorial we will use the population annealing Monte Carlo (PAMC) algorithm, so specify pamc.

    • +

  • seed is the seed that a pseudo-random number generator uses.

    • +
+

[algorithm.param] section sets the parameter space to be explored.

+
    +

  • min_list is a lower bound and max_list is an upper bound.

    • +

  • unit_list is step length in one Monte Carlo update (deviation of Gaussian distribution).

    • +
+

[algorithm.pamc] section sets the parameters for PAMC.

+
    +

  • numsteps_annealing is the number of interval steps between temperature decreasing.

    • +

  • bmin, bmax are the minimum and the maximum of inversed temperature, respectively.

    • +

  • Tnum is the number of (inversed) temperature points.

    • +

  • When Tlogspace is true, the temperature points are distributed uniformly in the logarithmic space.

    • +

  • nreplica_per_proc is the number of replicas (MC walkers) in one MPI process.

    • +
+
+
+

Calculation

+

First, move to the folder where the sample file is located. (Hereinafter, it is assumed that you are the root directory of ODAT-SE.)

+
$ cd sample/analytical/pamc
+
+
+

Then, run the main program. It will take a few secondes on a normal PC.

+
$ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

Here, the calculation is performed using MPI parallel with 4 processes. +If you are using Open MPI and you request more processes than the number of cores, add the --oversubscribe option to the mpiexec command.

+

When executed, a folder for each MPI rank will be created under the directory output, and trial_TXXX.txt files containing the parameters evaluated in each Monte Carlo step and the value of the objective function at each temperature (XXX is the index of points), and result_TXXX.txt files containing the parameters actually adopted will be created. +These files are concatnated into result.txt and trial.txt.

+

These files have the same format: the first two columns are time (step) and the index of walker in the process, the third is the (inversed) temperature, the fourth column is the value of the objective function, and the fifth and subsequent columns are the parameters. +The final two columns are the weight of walker (Neal-Jarzynski weight) and the index of the grand ancestor (the replica index at the beginning of the calculation).

+
# step walker T fx x1 x2 weight ancestor
+0 0 100.0 187.94429125133564 5.155393113805774 -2.203493345018569 1.0 0
+0 1 100.0 3.179380982615041 -3.7929742598748666 -3.5452766573635235 1.0 1
+0 2 100.0 108.25464277273859 0.8127003489802398 1.1465364357510186 1.0 2
+0 3 100.0 483.84183395038843 5.57417423682746 1.8381251624588506 1.0 3
+0 4 100.0 0.43633134370869153 2.9868796504069426 1.8428384502208246 1.0 4
+0 5 100.0 719.7992581349758 2.972577711255287 5.535680832873856 1.0 5
+0 6 100.0 452.4691017123836 -5.899340424701358 -4.722667479627368 1.0 6
+0 7 100.0 45.5355817998709 -2.4155554347674215 1.8769341969872393 1.0 7
+0 8 100.0 330.7972369561986 3.717750630491217 4.466110964691396 1.0 8
+0 9 100.0 552.0479484091458 5.575771168463163 2.684224163039442 1.0 9
+0 10 100.0 32.20027165958588 1.7097039347500953 2.609443449748964 1.0 10
+...
+
+
+

output/best_result.txt is filled with information about the parameter with the optimal objective function, the rank from which it was obtained, and the Monte Carlo step.

+
nprocs = 4
+rank = 3
+step = 1806
+walker = 74
+fx = 4.748689609377718e-06
+x1 = -2.805353724219707
+x2 = 3.131045687296453
+
+
+

Finally, output/fx.txt stores the statistics at each temperature point:

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.01 130.39908953806298 6.023477428315198 400 0.0 0.9378
+0.01258925411794167 83.6274790817115 3.83620542622489 400 -0.2971072297035158 0.930325
+0.015848931924611134 60.25390522675298 2.73578884504734 400 -0.5426399088244793 0.940375
+0.01995262314968879 47.20146188151557 2.3479083531465976 400 -0.7680892360649545 0.93715
+0.025118864315095794 41.118822390166315 1.8214854089575818 400 -0.9862114670289625 0.9153
+...
+
+
+

The first column is (inversed) temperature, and +the second/third ones are the mean and standard error of \(f(x)\), respectively. +The fourth column is the number of replicas and the fifth one is the logarithm of the ratio of the partition functions, \(\log(Z_n/Z_0)\), where \(Z_0\) is the partition function at the first temperature. +The sixth column is the acceptance ratio of MC updates.

+
+
+

Visualization

+

By illustrating result_T.txt, you can estimate regions where the function values become small. +In this case, the figure result_fx.pdf and result_T.pdf of the 2D parameter space is created by using the following command. +The color of symbols of result_fx.pdf and result_T.pdf mean R-factor and \(\beta\), respectively.

+

By executing the following command, the figures of two-dimensional parameter space res_T%.png will be generated where % stands for the indices of temperature. The symbol color corresponds to the function value.

+
$ python3 plot_result_2dmap.py
+
+
+

It is seen from the figures that the samples are concentrated near the minima of f(x) where the objective function has a small value.

+
+../_images/res_pamc.png +
+

Fig. 6 Plot of sampled parameters. The horizontal axis denotes x1, the vertical axis denotes x2, and the color represents the value of T (left) and f(x) (right), respectively.

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/en/tutorial/solver_simple.html b/manual/v3.0.0/en/tutorial/solver_simple.html new file mode 100644 index 00000000..f6dbd9f9 --- /dev/null +++ b/manual/v3.0.0/en/tutorial/solver_simple.html @@ -0,0 +1,135 @@ + + + + + + + + Adding a direct problem solver — ODAT-SE 3.0-dev documentation + + + + + + + + + + + + + +
+ + +
+

Adding a direct problem solver

+
+

Solver for benchmarking, analytical

+

ODAT-SE provides the analytical solver as a direct problem solver that can be used to test search algorithms.

+

To use the analytical solver, the users may set the name parameter in the [solver] section to "analytical", and choose the benchmark function f(x) in the function_name parameter. +For example, to use Himmelblau function, make an input file including the following lines:

+
[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+
+

For details of analytical solver, see the reference of the analytical solver.

+
+
+

How to add a direct problem solver

+

The easiest way to define and analyze a user-defined direct problem solver is to add it to the analytical solver as a function. +As an example, we will explain the case of adding the Booth function:

+
+\[f(x,y) = (x+2y-7)^2 + (2x+y-5)^2.\]
+

(The minimum point is \(f(1,3) = 0\).)

+

To do so, we need to download the source code of ODAT-SE and edit the file of analytical solver. +For instructions on how to download the source code and run odatse from the source code, see how to install. +analytical solver is defined in the src/odatse/solver/analytical.py, so we will edit this.

+

First, define the booth function as follows:

+
def booth(xs: np.ndarray) -> float:
+    """Booth function
+
+    it has one global minimum f(xs) = 0 at xs = [1,3].
+    """
+
+    if xs.shape[0] != 2:
+        raise RuntimeError(
+            f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one"
+        )
+    return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2
+
+
+

Next, insert the following code in the if branch of the Solver class’s constructor (__init__) to allow users to choose the booth function by the solver.function_name parameter of the input file.

+
elif function_name == "booth":
+    self.set_function(booth)
+
+
+

With this modified analytical solver, you can optimize the Booth function. +For example, to optimize it by the Nelder-Mead method, pass the following input file (input.toml):

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "minsearch"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+initial_list = [0, 0]
+
+[solver]
+name = "analytical"
+function_name = "booth"
+
+
+

to src/odatse_main.py script as follows:

+
$ python3 src/odatse_main.py input.toml
+
+... skipped ...
+
+Iterations: 38
+Function evaluations: 75
+Solution:
+x1 = 1.0000128043523089
+x2 = 2.9999832920260863
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/.buildinfo b/manual/v3.0.0/ja/.buildinfo new file mode 100644 index 00000000..c27909a5 --- /dev/null +++ b/manual/v3.0.0/ja/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 17417bc625633324060d6f3a855bb55d +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/manual/v3.0.0/ja/_images/plot_himmelblau.png b/manual/v3.0.0/ja/_images/plot_himmelblau.png new file mode 100644 index 00000000..3c0ecf62 Binary files /dev/null and b/manual/v3.0.0/ja/_images/plot_himmelblau.png differ diff --git a/manual/v3.0.0/ja/_images/res_bayes_plot.png b/manual/v3.0.0/ja/_images/res_bayes_plot.png new file mode 100644 index 00000000..debf1692 Binary files /dev/null and b/manual/v3.0.0/ja/_images/res_bayes_plot.png differ diff --git a/manual/v3.0.0/ja/_images/res_exchange.png b/manual/v3.0.0/ja/_images/res_exchange.png new file mode 100644 index 00000000..2e2b588d Binary files /dev/null and b/manual/v3.0.0/ja/_images/res_exchange.png differ diff --git a/manual/v3.0.0/ja/_images/res_limitation.png b/manual/v3.0.0/ja/_images/res_limitation.png new file mode 100644 index 00000000..78ae6a19 Binary files /dev/null and b/manual/v3.0.0/ja/_images/res_limitation.png differ diff --git a/manual/v3.0.0/ja/_images/res_mapper.png b/manual/v3.0.0/ja/_images/res_mapper.png new file mode 100644 index 00000000..d83e464d Binary files /dev/null and b/manual/v3.0.0/ja/_images/res_mapper.png differ diff --git a/manual/v3.0.0/ja/_images/res_minsearch.png b/manual/v3.0.0/ja/_images/res_minsearch.png new file mode 100644 index 00000000..b4a54fd1 Binary files /dev/null and b/manual/v3.0.0/ja/_images/res_minsearch.png differ diff --git a/manual/v3.0.0/ja/_images/res_pamc.png b/manual/v3.0.0/ja/_images/res_pamc.png new file mode 100644 index 00000000..89a6fe28 Binary files /dev/null and b/manual/v3.0.0/ja/_images/res_pamc.png differ diff --git a/manual/v3.0.0/ja/_sources/acknowledgement.rst.txt b/manual/v3.0.0/ja/_sources/acknowledgement.rst.txt new file mode 100644 index 00000000..b7b4aa6c --- /dev/null +++ b/manual/v3.0.0/ja/_sources/acknowledgement.rst.txt @@ -0,0 +1,7 @@ +謝辞 +================================ + +本ソフトウェアの開発は、科研費 19H04125, 20H00581, 21K19773, 23K18465 および東京大学物性研究所 ソフトウェア開発・高度化プロジェクト (2020, 2021, 2024 年度) の支援を受け開発されました。 + +本ソフトウェアの設計・変数命名の一部は `abics `_ を参考にしています。 +また、ソルバーの追加方法について、塚本恭平氏(物性研)にチュートリアルを追加していただきました。この場を借りて感謝します。 diff --git a/manual/v3.0.0/ja/_sources/algorithm/bayes.rst.txt b/manual/v3.0.0/ja/_sources/algorithm/bayes.rst.txt new file mode 100644 index 00000000..e0faae12 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/algorithm/bayes.rst.txt @@ -0,0 +1,196 @@ +ベイズ最適化 ``bayes`` +******************************* + +.. _PHYSBO: https://pasums.issp.u-tokyo.ac.jp/physbo + +``bayes`` はベイズ最適化を用いてパラメータ探索を行う ``Algorithm`` です。 +実装には `PHYSBO`_ を用いています。 + +前準備 +~~~~~~ +あらかじめ `PHYSBO`_ をインストールしておく必要があります。 + +.. code-block:: bash + + $ python3 -m pip install physbo + +`mpi4py `_ がインストールされている場合、MPI 並列計算が可能です。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[``algorithmparam``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索パラメータ空間を定義します。 + +``mesh_path`` が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。 + +``mesh_path`` が定義されていない場合は、 ``min_list``, ``max_list``, ``num_list`` を用いて、 +各パラメータについて等間隔なグリッドを作成します。 + +- ``mesh_path`` + + 形式: string型 + + 説明: メッシュデータの情報が記載された参照用ファイルへのパス。 + +- ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + +- ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + +- ``num_list`` + + 形式: 整数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる数。 + +[``algorithm.bayes``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +手法のハイパーパラメータを定義します。 + +- ``random_max_num_probes`` + + 形式： int型 (default: 20) + + 説明: ベイズ最適化を行う前に行うランダムサンプリングの回数(パラメータとスコアが初めに無い場合にはランダムサンプリングは必須)。 + +- ``bayes_max_num_probes`` + + 形式： int型 (default: 40) + + 説明: ベイズ最適化を行う回数。 + +- ``score`` + + 形式: string型 (default: ``TS`` ) + + 説明: スコア関数を指定するパラメータ。 + ``EI``, ``PI``, ``TS`` より選択可能で、それぞれ "expected improvement", "probability of improvement", "Thompson sampling" を行います。 + +- ``interval`` + + 形式： int型 (default: 5) + + 説明: 指定したインターバルごとに、ハイパーパラメータを学習します。負の値を指定すると、ハイパーパラメータの学習は行われません。 + 0を指定すると、ハイパーパラメータの学習は最初のステップでのみ行われます。 + +- ``num_rand_basis`` + + 形式： int型 (default: 5000) + + 説明： 基底関数の数。0を指定した場合、Bayesian linear modelを利用しない通常のガウシアンプロセスが行われます。 + + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス、 +2列目以降は ``[solver.param]`` セクションにある、 +``string_list`` で定義された変数に入る値が入ります。 + +以下、サンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``BayesData.txt`` +^^^^^^^^^^^^^^^^^^^^^^ +最適化過程の各ステップにおいて、 +パラメータと対応する目的関数の値が、 +これまでの最適パラメータとそのステップで探索したパラメータの順に記載されます。 + +.. code-block:: + + #step z1 z2 R-factor z1_action z2_action R-factor_action + 0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885 + 1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033 + 2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189 + 3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794 + ... + + +リスタート +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +コンストラクタの引数 ``run_mode`` に実行モードを指定します。 +以下はそれぞれ ``odatse`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。 +各モードの動作は次のとおりです。 + +- ``"initial"`` (デフォルト) + + 初期化して実行します。 + まず、ランダムサンプリングを ``random_max_num_probes`` に指定した回数だけ行います。 + 次に、ベイズ最適化を ``bayes_max_num_probes`` に指定した回数実行します。 + + チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。 + + #. ランダムサンプリングが終了したとき + #. ベイズ最適化の繰り返しの途中で、指定したステップ数または実行時間が経過したとき + #. 実行の終了時 + + +- ``"resume"`` + + 実行が中断した際に、最も新しいチェックポイントから実行を再開します。 + 並列数などの計算条件は前と同じにする必要があります。 + + なお、並列実行の場合、実行を中断して resume した結果は、中断なしで実行した結果と完全には一致しません。 + +- ``"continue"`` + + 終了時の状態からベイズ最適化の繰り返しを継続して実行するモードです。 + ``bayes_max_num_probes`` の値を増やしてプログラムを実行してください。 + 繰り返しステップカウントはそのまま引き継がれます。 + + 例: 前の計算で ``bayes_max_num_probes = 100`` として 100ステップ計算した後、次の計算で ``bayes_max_num_probes = 200`` として continue モードで実行すると、101ステップ目から 200ステップ目までの計算を行います。 + + +アルゴリズム解説 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`ベイズ最適化 (Bayesian optimization, BO) `_ は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。 + +BO では目的関数 :math:`f(\vec{x})` を、評価が早く最適化のしやすいモデル関数(多くの場合ガウス過程) :math:`g(\vec{x})` で近似します。 +:math:`g` は、あらかじめ適当に決められたいくつかの点(訓練データセット) :math:`\{\vec{x}_i\}_{i=1}^N` での目的関数の値 :math:`\{f(\vec{x}_i)\}_{i=1}^N` をよく再現するように訓練されます。 +パラメータ空間の各点において、訓練された :math:`g(\vec{x})` の値の期待値およびその誤差から求められる「スコア」 (acquition function) が最適になるような点 :math:`\vec{x}_{N+1}` を次の計算候補点として提案します。 +:math:`f(\vec{x}_{N+1})` を評価し、 訓練データセットに追加、 :math:`g` を再訓練します。 +こうした探索を適当な回数繰り返した後、目的関数の値が最も良かったものを最適解として返します。 + +少ない誤差でより良い期待値を与える点は、正解である可能性こそ高いですが、すでに十分な情報があると考えられるので、モデル関数の精度向上にはあまり寄与しません。 +逆に、誤差の大きな点は正解ではないかもしれませんが、情報の少ない場所であり、モデル関数の更新には有益だと考えられます。 +前者を選ぶことを「活用」、後者を選ぶことを「探索」とよび、両者をバランス良く行うのが重要です。 +「スコア」の定義はこれらをどう選ぶかを定めます。 + +ODAT-SE では、ベイズ最適化のライブラリとして、 `PHYSBO`_ を用います。 +PHYSBO は ``mapper_mpi`` のように、あらかじめ決めておいた候補点の集合に対して「スコア」を計算して、最適解を提案します。 +候補点の集合を分割することでMPI 並列実行が可能です。 +また、 訓練データの点数 :math:`N` に対して線形の計算量でモデル関数の評価、ひいては「スコア」の計算が可能となるようなカーネルを用いています。 +PHYSBO では「スコア」関数として "expected improvement (EI)", "probability of improvement (PI)", "Thompson sampling (TS)" が利用できます。 diff --git a/manual/v3.0.0/ja/_sources/algorithm/exchange.rst.txt b/manual/v3.0.0/ja/_sources/algorithm/exchange.rst.txt new file mode 100644 index 00000000..ae692792 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/algorithm/exchange.rst.txt @@ -0,0 +1,348 @@ +交換モンテカルロ法 ``exchange`` +=================================== + +``exchange`` はレプリカ交換モンテカルロ法を用いてパラメータ探索を行う ``Algorithm`` です。 + +前準備 +~~~~~~~~ + +MPI並列を利用する場合は、あらかじめ `mpi4py `_ をインストールしておきます。 + +.. code-block:: + + $ python3 -m pip install mpi4py + +入力パラメータ +~~~~~~~~~~~~~~~~~~~ + +サブセクション ``param`` と ``exchange`` を持ちます。 + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索空間を定義します。 +``mesh_path`` キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。 + +- 連続空間 + + - ``initial_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。 + + - ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + + - ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + + - ``step_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: モンテカルロ更新の際の変化幅(ガウス分布の偏差)です。 + +- 離散空間 + + - ``mesh_path`` + + 形式: ファイルパス + + 説明: メッシュ定義ファイル。 + + - ``neighborlist_path`` + + 形式: ファイルパス + + 説明: 近傍リスト定義ファイル。 + + +[``exchange``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + 形式: 整数値。 + + 説明: モンテカルロ更新を行う回数。 + +- ``numsteps_exchange`` + + 形式: 整数値。 + + 説明: 「温度」のレプリカ交換を行う頻度。この回数だけモンテカルロ更新を行ったらレプリカ交換を実行します。 + +- ``Tmin`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最小値。 + +- ``Tmax`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最大値。 + +- ``bmin`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最小値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``bmax`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最大値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``Tlogspace`` + + 形式: 真偽値。 (default: true) + + 説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。 + true のときは対数空間で等分割します。 + +- ``nreplica_per_proc`` + + 形式: 整数。 (default: 1) + + 説明: ひとつのMPI プロセスが担当するレプリカの数。 + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス (実際には使用されません)、 +2列目以降は探索空間の座標を指定します。 + +以下、サンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +近傍リスト定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +離散空間をモンテカルロ法で探索する場合、各点 :math:`i` ごとに次に移動できる点 :math:`j` を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。 + +1列目に始点の番号 :math:`i` を記載し、 +2列目以降に :math:`i` から移動できる終点 :math:`j` を列挙します。 + +近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール ``odatse_neighborlist`` が提供されています。 +詳細は :doc:`../tool` を参照してください。 + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ +各レプリカについて、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの温度、4列目に目的関数の値、5列目以降にパラメータが記載されます。 + +.. code-block:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861 + 2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ +各レプリカについて、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +``trial.txt`` と同一の書式です。 + +.. code-block:: + + # step walker T fx z1 z2 + 0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586 + 3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154 + + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ +サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。 + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + +``result_T#.txt`` +^^^^^^^^^^^^^^^^^^^ +サンプリング結果を温度ごとにまとめ直したものです。 +``#`` は温度点の番号です。 +ファイルの1 列目はステップ数、2列目は全体での walker 番号、3列目は目的関数の値、 4列目以降は探索パラメータの値です。 + +.. code-block:: + + # T = 1.0 + 0 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 1 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 2 15 28.70157662892569 3.3139009347685118 -4.20946994566609 + 3 15 28.98676409223712 3.7442621319489637 -3.868754990884034 + +リスタート +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +コンストラクタの引数 ``run_mode`` に実行モードを指定します。 +以下はそれぞれ ``odatse`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。 +各モードの動作は次のとおりです。 + +- ``"initial"`` (デフォルト) + + 初期化して実行します。 + チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。 + + #. 指定したステップ数または実行時間が経過したとき + #. 実行の終了時 + + +- ``"resume"`` + + 実行が中断した際に、最も新しいチェックポイントから実行を再開します。 + 並列数などの計算条件は前と同じにする必要があります。 + +- ``"continue"`` + + 終了時の状態からサンプリングの繰り返しを継続して実行するモードです。 + ``numsteps`` の値を増やしてプログラムを実行してください。 + 繰り返しステップカウントはそのまま引き継がれます。 + + 例: 前の計算で ``numsteps = 1000`` として 1000ステップ計算した後、次の計算で ``numsteps = 2000`` として continue モードで実行すると、1001ステップ目から 2000ステップ目までの計算を行います。 + + +アルゴリズム解説 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +マルコフ連鎖モンテカルロ法 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +モンテカルロ法(モンテカルロサンプリング)では、パラメータ空間中を動き回る walker :math:`\vec{x}` を重み :math:`W(\vec{x})` に従って確率的に動かすことで目的関数の最適化を行います。 +重み :math:`W(\vec{x})` として、「温度」 :math:`T > 0` を導入して :math:`W(\vec{x}) = e^{-f(\vec{x})/T}` とすることが一般的です(ボルツマン重み)。 +ほとんどの場合において、 :math:`W` に基づいて直接サンプリングする (walker を生成する) のは不可能なので、 walker を確率的に少しずつ動かすことで、頻度分布が :math:`W` に従うように時系列 :math:`\{\vec{x}_t\}` を生成します (マルコフ連鎖モンテカルロ法, MCMC)。 +:math:`\vec{x}` から :math:`\vec{x}'` へ遷移する確率を :math:`p(\vec{x}' | \vec{x})` とすると、 + +.. math:: + + W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x}) + +となるように :math:`p` を定めれば(釣り合い条件)、時系列 :math:`\{\vec{x}_t\}` の頻度分布が :math:`W(\vec{x})` に収束することが示されます。 [#mcmc_condition]_ +実際の計算では、より強い制約である詳細釣り合い条件 + +.. math:: + + p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x}) + +を課すことがほとんどです。 両辺で :math:`\vec{x}` についての和を取ると釣り合い条件に帰着します。 + +:math:`p` を求めるアルゴリズムはいくつか提案されていますが、 ODAT-SE では Metropolis-Hasting 法 (MH法) を用います。 +MH 法では、遷移プロセスを提案プロセスと採択プロセスとに分割します。 + +1. 提案確率 :math:`P(\vec{x} | \vec{x}_t)` で候補点 :math:`\vec{x}` を生成します + + 提案確率 :math:`P` としては :math:`\vec{x}_t` を中心とした一様分布やガウス関数などの扱いやすいものを利用します + +2. 提案された候補点 :math:`\vec{x}` を採択確率 :math:`Q(\vec{x}, | \vec{x}_t)` で受け入れ、 :math:`\vec{x}_{t+1} = \vec{x}` とします + + 受け入れなかった場合は :math:`\vec{x}_{t+1} = \vec{x}_t` とします + +採択確率 :math:`Q(\vec{x} | \vec{x}_t)` は + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right] + +とします。 +この定義が詳細釣り合い条件を満たすことは、詳細釣り合いの式に代入することで簡単に確かめられます。 +特に、重みとしてボルツマン因子を、提案確率として対称なもの :math:`P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})` を用いたときには、 + +.. math:: + + Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right] + +という更に簡単な形になります。 + +:math:`\Delta f = f(\vec{x}) - f(\vec{x}_t)` とおいて、 +:math:`\Delta f \le 0` のときに :math:`Q = 1` となることを踏まえると、 +MH 法によるMCMC は次のようになります。 + +1. 現在地点の近くからランダムに次の座標の候補を選び、目的関数 :math:`f` の値を調べる +2. :math:`\Delta f \le 0` ならば(山を下る方向ならば)移動する +3. :math:`\Delta f > 0` ならば採択確率 :math:`Q = e^{-\Delta f / T}` で移動する +4. 1-3 を適当な回数繰り返す + +得られた時系列のうち、目的関数の値が一番小さいものを最適解とします。 +3 番のプロセスのおかげで、 :math:`\Delta f \sim T` ぐらいの山を乗り越えられるので、局所最適解にトラップされた場合にも脱出可能です。 + +レプリカ交換モンテカルロ法 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +モンテカルロ法による最適化では、温度 :math:`T` は非常に重要なハイパーパラメータとなっています。 +モンテカルロ法では、温度 :math:`T` 程度の山を乗り越えられますが、逆にそれ以上の深さの谷からは容易に脱出できません。 +そのため、局所解へのトラップを防ぐためには温度を上げる必要があります。 +一方で、 :math:`T` よりも小さい谷は谷として見えなくなるため、得られる :math:`\min f(\vec{x})` の精度も :math:`T` 程度になり、精度を上げるためには温度を下げる必要があります。 +ここから、最適解を探すためには温度 :math:`T` を注意深く決める必要があることがわかります。 + +この問題を解決する方法として、温度 :math:`T` を固定せずに更新していくというものがあります。 +たとえば、焼きなまし法 (simulated annealing) では、温度をステップごとに徐々に下げていきます。 +焼戻し法 (simulated tempering) は、温度をハイパーパラメータではなく、サンプリングすべきパラメータとして扱い、(詳細)釣り合い条件を満たすように更新することで、加熱と冷却を実現します。温度を下げることで谷の詳細を調べ、温度を上げることで谷から脱出します。 +レプリカ交換モンテカルロ法 (replica exchange Monte Carlo) は焼戻し法を更に発展させた手法で、並列焼戻し法 (parallel tempering) とも呼ばれます。 +レプリカ交換モンテカルロ法では、レプリカと呼ばれる複数の系を、それぞれ異なる温度で並列にモンテカルロシミュレーションします。 +そして、ある一定間隔で、(詳細)釣り合い条件を満たすように他のレプリカと温度を交換します。 +焼戻し法と同様に、温度を上下することで谷を調べたり脱出したりするのですが、各温度点について、かならずレプリカのどれかが対応しているため、全体として特定の温度に偏ることがなくなります。 +また、複数の MPI プロセスを用意してそれぞれレプリカを担当させることで簡単に並列化可能です。 +数多くのレプリカを用意することで温度間隔が狭まると、温度交換の採択率も上がるため、大規模並列計算に特に向いたアルゴリズムです。 +有限温度由来の「ぼやけ」がどうしても生まれるので、モンテカルロ法の結果を初期値として ``minsearch`` をするのがおすすめです。 + +.. only:: html + + .. rubric:: 脚注 + +.. [#mcmc_condition] 正確には、収束のためには非周期性とエルゴード性も必要です。 diff --git a/manual/v3.0.0/ja/_sources/algorithm/index.rst.txt b/manual/v3.0.0/ja/_sources/algorithm/index.rst.txt new file mode 100644 index 00000000..d25e07b9 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/algorithm/index.rst.txt @@ -0,0 +1,19 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +探索アルゴリズム +==================== + +探索アルゴリズム ``Algorithm`` は ``Solver`` の結果 :math:`f(x)` を用いて +パラメータ空間 :math:`\mathbf{X} \ni x` を探索し、 :math:`f(x)` の最小化問題を解きます。 + +.. toctree:: + :maxdepth: 1 + + minsearch + mapper_mpi + exchange + pamc + bayes diff --git a/manual/v3.0.0/ja/_sources/algorithm/mapper_mpi.rst.txt b/manual/v3.0.0/ja/_sources/algorithm/mapper_mpi.rst.txt new file mode 100644 index 00000000..5dc4b801 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/algorithm/mapper_mpi.rst.txt @@ -0,0 +1,131 @@ +グリッド型探索 ``mapper`` +****************************** + +``mapper_mpi`` はパラメータ空間中の候補点をあらかじめ用意しておいて、そのすべてで :math:`f(x)` を計算することで最小値を探索するアルゴリズムです。 +MPI 実行した場合、候補点の集合を等分割して各プロセスに自動的に割り振ることで自明並列計算を行います。 + +前準備 +~~~~~~~ + +MPI 並列を行う場合は、 `mpi4py `_ をインストールしておく必要があります。 + +.. code-block:: + + $ python3 -m pip install mpi4py + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _mapper_input_param: + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索パラメータ空間を定義します。 + +``mesh_path`` が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。 + +``mesh_path`` が定義されていない場合は、 ``min_list``, ``max_list``, ``num_list`` を用いて、 +各パラメータについて等間隔なグリッドを作成します。 + +- ``mesh_path`` + + 形式: string型 + + 説明: メッシュ定義ファイルへのパス。 + +- ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + +- ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + +- ``num_list`` + + 形式: 整数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる数。 + + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1 + ``dimension`` 列のテキストファイルで、 +1列目にメッシュのインデックス、 +2列目以降は探索パラメータ :math:`x` に対応する値を記載します。 +また、 ``#`` から始まる行はコメントとして無視されます。 + +以下、2次元パラメータ空間探索のサンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +各メッシュでの候補パラメータと、その点での目的関数の値が記載されたファイルです。 +メッシュデータは、入力ファイルの ``[solver.param]`` セクションにある ``string_list`` で定義された変数の順番で記載され、最後に目的関数の値が記載されます。 + +以下、出力例です。 + +.. code-block:: + + 6.000000 6.000000 0.047852 + 6.000000 5.750000 0.055011 + 6.000000 5.500000 0.053190 + 6.000000 5.250000 0.038905 + 6.000000 5.000000 0.047674 + 6.000000 4.750000 0.065919 + 6.000000 4.500000 0.053675 + 6.000000 4.250000 0.061261 + 6.000000 4.000000 0.069351 + 6.000000 3.750000 0.071868 + ... + +リスタート +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +コンストラクタの引数 ``run_mode`` に実行モードを指定します。 +以下はそれぞれ ``odatse`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。 +各モードの動作は次のとおりです。 + +- ``"initial"`` (デフォルト) + + 初期化して実行します。 + チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。 + + #. 指定した数のグリッド点を評価したとき、または指定した実行時間が経過したとき + #. 実行の終了時 + +- ``"resume"`` + + 実行が中断した際に、最も新しいチェックポイントから実行を再開します。 + 並列数などの計算条件は前と同じにする必要があります。 + +- ``"continue"`` + + continue には対応していません。 diff --git a/manual/v3.0.0/ja/_sources/algorithm/minsearch.rst.txt b/manual/v3.0.0/ja/_sources/algorithm/minsearch.rst.txt new file mode 100644 index 00000000..37caab07 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/algorithm/minsearch.rst.txt @@ -0,0 +1,144 @@ +Nelder-Mead 法 ``minsearch`` +******************************* + +.. _scipy.optimize.minimize: https://docs.scipy.org/doc/scipy/reference/optimize.minimize-neldermead.html + +``minsearch`` は `Nelder-Mead 法 `_ (a.k.a. downhill simplex 法) によって最適化を行います。 +Nelder-Mead 法では、 パラメータ空間の次元を :math:`D` として、 :math:`D+1` 個の座標点の組を、各点での目的関数の値に応じて系統的に動かすことで最適解を探索します。 + +重要なハイパーパラメータとして、座標の初期値があります。 +局所最適解にトラップされるという問題があるので、初期値を変えた計算を何回か繰り返して結果を確認することをおすすめします。 + +ODAT-SEは、SciPy の ``scipy.optimize.minimize(method="Nelder-Mead")`` 関数を用いています。 +詳しくは `公式ドキュメント `_ をご参照ください。 + + +前準備 +~~~~~~ + +あらかじめ `scipy `_ をインストールしておく必要があります。 :: + + python3 -m pip install scipy + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サブセクション ``param`` と ``minimize`` を持ちます。 + +.. _minsearch_input_param: + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``initial_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。 + +- ``unit_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: 各パラメータの単位。 + 探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 + 簡易的な無次元化・正規化を行います。 + 定義しなかった場合にはすべての次元で 1.0 となります。 + +- ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + 最適化中にこの値を下回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + +- ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + 最適化中にこの値を上回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + +[``minimize``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Nelder-Mead 法のハイパーパラメータを設定します。 +詳細は `scipy.optimize.minimize`_ のドキュメントを参照してください。 + +- ``initial_scale_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: Nelder-Mead 法の初期 simplex を作るために、初期値からずらす差分。 + ``initial_list`` と、 ``initial_list`` に ``initial_scale_list`` の成分ひとつを足してできるdimension 個の点を 合わせたものが ``initial_simplex`` として使われます。 + 定義しなかった場合、各次元に 0.25 が設定されます。 + +- ``xatol`` + + 形式: 実数型 (default: 1e-4) + + 説明: Nelder-Mead 法の収束判定に使うパラメータ + +- ``fatol`` + + 形式: 実数型 (default: 1e-4) + + 説明: Nelder-Mead 法の収束判定に使うパラメータ + +- ``maxiter`` + + 形式: 整数 (default: 10000) + + 説明: Nelder-Mead 法の反復回数の最大値 + +- ``maxfev`` + + 形式: 整数 (default: 100000) + + 説明: 目的関数を評価する回数の最大値 + + +出力ファイル +~~~~~~~~~~~~~~~~~ + +``SimplexData.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +最小値を求める途中経過に関する情報を出力します。 +1行目はヘッダー、2行目以降にstep、入力ファイルの ``[solver.param]`` セクションにある +``string_list`` で定義された変数の値、最後に関数の値が出力されます。 + +以下、出力例です。 + +.. code-block:: + + #step z1 z2 z3 R-factor + 0 5.25 4.25 3.5 0.015199251773721183 + 1 5.25 4.25 3.5 0.015199251773721183 + 2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375 + 3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261 + 4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + 5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159 + +``res.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +最終的に得られた目的関数の値とその時のパラメータの値を記載しています。 +最初に目的関数、その後は入力ファイルの ``[solver.param]`` セクションにある ``string_list`` で定義された変数の値が順に記載されます。 + +以下、出力例です。 + +.. code-block:: + + fx = 7.382680568652868e-06 + z1 = 5.230524973874179 + z2 = 4.370622919269477 + z3 = 3.5961444501081647 + + +リスタート +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nelder-Mead法による最適値探索はリスタートに対応していません。 diff --git a/manual/v3.0.0/ja/_sources/algorithm/pamc.rst.txt b/manual/v3.0.0/ja/_sources/algorithm/pamc.rst.txt new file mode 100644 index 00000000..fa77dc4e --- /dev/null +++ b/manual/v3.0.0/ja/_sources/algorithm/pamc.rst.txt @@ -0,0 +1,508 @@ +ポピュレーションアニーリングモンテカルロ法 ``pamc`` +========================================================= + +``pamc`` はポピュレーションアニーリングモンテカルロ法を用いてパラメータ探索を行う ``Algorithm`` です。 + +前準備 +~~~~~~~~ + +MPI 並列をする場合にはあらかじめ `mpi4py `_ をインストールしておく必要があります。 + +.. code-block:: bash + + $ python3 -m pip install mpi4py + +入力パラメータ +~~~~~~~~~~~~~~~~~~~ + +サブセクション ``param`` と ``pamc`` を持ちます。 + +[``param``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +探索空間を定義します。 +``mesh_path`` キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。 + +- 連続空間 + + - ``initial_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。 + + - ``min_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最小値。 + モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + + - ``max_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: パラメータが取りうる最大値。 + モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 + ソルバーは評価されずに、値が無限大だとみなされます。 + + - ``step_list`` + + 形式: 実数型のリスト。長さはdimensionの値と一致させます。 + + 説明: モンテカルロ更新の際の変化幅(ガウス分布の偏差)です。 + +- 離散空間 + + - ``mesh_path`` + + 形式: ファイルパス + + 説明: メッシュ定義ファイル。 + + - ``neighborlist_path`` + + 形式: ファイルパス + + 説明: 近傍リスト定義ファイル。 + + +[``pamc``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``numsteps`` + + 形式: 整数値。 + + 説明: モンテカルロ更新を行う総回数。 + +- ``numsteps_annealing`` + + 形式: 整数値。 + + 説明: 「温度」を下げる頻度。この回数モンテカルロ更新を行った後に温度が下がります。 + +- ``Tnum`` + + 形式: 整数値。 + + 説明: 「温度」点の数。 + +- ``Tmin`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最小値。 + +- ``Tmax`` + + 形式: 実数値。 + + 説明: 「温度」(:math:`T`)の最大値。 + +- ``bmin`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最小値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``bmax`` + + 形式: 実数値。 + + 説明: 「逆温度」(:math:`\beta = 1/T`)の最大値。 + 温度と逆温度はどちらか片方だけを指定する必要があります。 + +- ``Tlogspace`` + + 形式: 真偽値。 (default: true) + + 説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。 + true のときは対数空間で等分割します。 + +- ``nreplica_per_proc`` + + 形式: 整数。 (default: 1) + + 説明: ひとつのMPI プロセスが担当するレプリカの数。 + +- ``resampling_interval`` + + 形式: 整数。 (default: 1) + + 説明: レプリカのリサンプリングを行う頻度。この回数だけ温度降下を行った後にリサンプリングが行われます。 + +- ``fix_num_replicas`` + + 形式: 真偽値。 (default: true) + + 説明: リサンプリングの際、レプリカ数を固定するかどうか。 + +ステップ数について +******************** + +``numsteps``, ``numsteps_annealing``, ``numT`` の3つのうち、どれか2つを同時に指定してください。 +残りの1つは自動的に決定されます。 + +アルゴリズム補助ファイル +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メッシュ定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス(実際には使用されません)、 +2列目以降は探索空間の座標を指定します。 + +以下、サンプルを記載します。 + +.. code-block:: + + 1 6.000000 6.000000 + 2 6.000000 5.750000 + 3 6.000000 5.500000 + 4 6.000000 5.250000 + 5 6.000000 5.000000 + 6 6.000000 4.750000 + 7 6.000000 4.500000 + 8 6.000000 4.250000 + 9 6.000000 4.000000 + ... + + +近傍リスト定義ファイル +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +離散空間をモンテカルロ法で探索する場合、各点 :math:`i` ごとに次に移動できる点 :math:`j` を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。 + +1列目に始点の番号 :math:`i` を記載し、 +2列目以降に :math:`i` から移動できる終点 :math:`j` を列挙します。 + +近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール ``odatse_neighborlist`` が提供されています。 +詳細は :doc:`../tool` を参照してください。 + +.. code-block:: + + 0 1 2 3 + 1 0 2 3 4 + 2 0 1 3 4 5 + 3 0 1 2 4 5 6 7 + 4 1 2 3 5 6 7 8 + 5 2 3 4 7 8 9 + ... + +出力ファイル +~~~~~~~~~~~~~~~~~~~~~ + +``RANK/trial_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +各温度点(``#``) ごと、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの逆温度、4列目に目的関数の値、5列目からパラメータが記載されます。 +最後の2列はそれぞれレプリカの重み (Neal-Jarzynski weight) と祖先(計算開始時のレプリカ番号)です。 + +.. code-block:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + + +``RANK/trial.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +``trial_T#.txt`` をすべてまとめたものです。 + +``RANK/result_T#.txt`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +各温度点、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +``trial.txt`` と同一の書式です。 + +.. code-block:: + + # step walker beta fx x1 weight ancestor + 0 0 0.0 73.82799488298886 8.592321856342956 1.0 0 + 0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1 + 0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2 + 0 3 0.0 34.913851603463 -5.908794428939206 1.0 3 + 0 4 0.0 1.834671825646121 1.354500581633733 1.0 4 + 0 5 0.0 3.65151610695736 1.910894059585031 1.0 5 + ... + +``RANK/result.txt`` +^^^^^^^^^^^^^^^^^^^^^ + +``result_T#.txt`` をすべてまとめたものです。 + + +``best_result.txt`` +^^^^^^^^^^^^^^^^^^^^ + +サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。 + +.. code-block:: + + nprocs = 4 + rank = 2 + step = 65 + fx = 0.008233957976993406 + z1 = 4.221129370933539 + z2 = 5.139591716517661 + + +``fx.txt`` +^^^^^^^^^^^^^^ + +各温度ごとに、全レプリカの情報をまとめたものです。 +1列目は逆温度が、2列目と3列目には目的関数の期待値およびその標準誤差が、4列目にはレプリカの総数が、5列目には規格化因子(分配関数)の比の対数 + +.. math:: + + \log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)} + +が、6列目にはモンテカルロ更新の採択率が出力されます。 +ここで :math:`\beta_0` は計算している :math:`\beta` の最小値です。 + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804 + 0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058 + 0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004 + ... + + +リスタート +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +コンストラクタの引数 ``run_mode`` に実行モードを指定します。 +以下はそれぞれ ``odatse`` コマンドの引数の ``--init``, ``--resume``, ``--cont`` に対応します。 +各モードの動作は次のとおりです。 + +- ``"initial"`` (デフォルト) + + 初期化して実行します。 + チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。 + + #. 各温度点の計算が終わった時点で、指定したステップ数または実行時間が経過したとき + #. 実行の終了時 + + +- ``"resume"`` + + 実行が中断した際に、最も新しいチェックポイントから実行を再開します。 + 並列数などの計算条件は前と同じにする必要があります。 + +- ``"continue"`` + + 実行終了後の状態から継続して実行します。 + 温度点のリストを、前の計算から連続するように指定する必要があります。 + + 前の計算で ``Tmax=`` :math:`T^{(1)}` から ``Tmin=`` :math:`T^{(2)}` に下げた場合、 + 次の計算では ``Tmax=`` :math:`T^{(2)}`, ``Tmin=`` :math:`T^{(3)}` のように指定します。 + 新たな計算では、 :math:`T^{(2)}` から :math:`T^{(3)}` までを ``Tnum`` に分割した温度点の列 + :math:`T_0 = T^{(2)}`, :math:`T_1`,..., :math:`T_{\text{Tnum}-1}=T^{(3)}` + について計算を行います。(Tnum は前の計算から変更して構いません。) + + +アルゴリズム解説 +~~~~~~~~~~~~~~~~~~~ + +問題と目的 +^^^^^^^^^^^^ + +分布パラメータ :math:`\beta_i` のもとでの配位 :math:`x` の重みを +:math:`f_i(x)` と書くと(例えばボルツマン因子 :math:`f_i(x) = \exp\left[-\beta_i E(x)\right]`\ )、 +:math:`A` の期待値は + +.. math:: + + \langle A\rangle_i + = \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} + = \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) + = \int \mathrm{d}xA(x)\tilde{f}_i(x) + +とかけます。 +ここで :math:`Z = \int \mathrm{d} x f_i(x)` は規格化因子(分配関数)で、 :math:`\tilde{f}(x) = f(x)/Z` は配位 :math:`x` の確率密度です。 + +目的は複数の分布パラメータについてこの期待値および規格化因子(の比)を数値的に求めることです。 + +Annealed Importance Sampling (AIS) [1] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +次の同時確率分布 + +.. math:: + + \tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0) + +を満たす点列 :math:`\{x_i\}` を考えます。ここで + +.. math:: + + \tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} + +であり、 :math:`T_i(x, x')` は :math:`\beta_i` のもとでの配位 :math:`x` +から :math:`x'` への遷移確率で、釣り合い条件 + +.. math:: + + + \int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x') + +を満たすようにとります(つまりは普通のMCMCにおける遷移確率行列)。 + +.. math:: + + + \int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) + = \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) + = 1 + +となるので、 :math:`\tilde{f}_n(x_n)` は +:math:`\tilde{f}(x_0, x_1, \dots, x_n)` の周辺分布 + +.. math:: + + + \tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n) + +です。 +これを利用すると、 :math:`\tilde{f}_n` における平均値 :math:`\langle A \rangle_n` は拡張した配位の重み付き平均として + +.. math:: + + + \begin{split} + \langle A \rangle_n + &\equiv + \int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) + \end{split} + +と表せます。 + +さて、残念ながら :math:`\tilde{f}(x_0, x_1, \dots, x_n)` +に従うような点列を直接生成することは困難です。そこでもっと簡単に、 + +1. 確率 :math:`\tilde{f}_0(x)` に従う :math:`x_0` を生成する + + - 例えば MCMC を利用する + +2. :math:`x_i` から :math:`T_{i+1}(x_i, x_{i+1})` によって :math:`x_{i+1}` を生成する + + - :math:`T_{i+1}` は釣り合い条件を満たすような遷移確率行列なので、普通にMCMCを行えば良い + +という流れに従って点列 :math:`\{x_i\}` を生成すると、これは同時確率分布 + +.. math:: + + \tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n) + +に従います。これを利用すると期待値 :math:`\langle A \rangle_n` は + +.. math:: + + + \begin{split} + \langle A \rangle_n + &= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ + &= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ + &= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + \end{split} + +と評価できます (reweighting method)。 +:math:`\tilde{f}` と :math:`\tilde{g}` との比は、 + +.. math:: + + + \begin{split} + \frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ + &= + \frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} + \prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \frac{f_n(x_n)}{f_0(x_0)} + \prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ + &= + \frac{Z_0}{Z_n} + \prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ + &\equiv + \frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n) + \end{split} + +とかけるので、期待値は + +.. math:: + + \langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} + = \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n} + +となります。 +規格化因子の比 :math:`Z_n/Z_0` は :math:`\langle 1 \rangle_n = 1` を用いると + +.. math:: + + \frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n} + +と評価できるので、 :math:`A` の期待値は + +.. math:: + + \langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}} + +という、重み付き平均の形で評価できます。 +この重み :math:`w_n` を Neal-Jarzynski 重みと呼びます。 + +population annealing (PA) [2] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +AIS を使うと各 :math:`\beta` に対する期待値を重み付き平均という形で計算できますが、 +:math:`\beta` の幅が大きくなると重み :math:`w` の分散が大きくなってしまいます。 +そのため、適当な周期で確率 :math:`p^{(k)} = w^{(k)} / \sum_k w^{(k)}` に従いレプリカをリサンプリングし、 +レプリカに割当られた重みをリセット :math:`(w=1)` します。 + +PAMC のアルゴリズムは次の擬似コードで示されます: + +.. code-block:: python + + for k in range(K): + w[0, k] = 1.0 + x[0, k] = draw_from(β[0]) + for i in range(1, N): + for k in range(K): + w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) ) + if i % interval == 0: + x[i, :] = resample(x[i, :], w[i, :]) + w[i, :] = 1.0 + for k in range(K): + x[i, k] = transfer(x[i-1, k], β[i]) + a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:]) + +リサンプリング手法として、レプリカ数を固定する方法[2]と固定しない方法[3]の2通りがあります。 + +参考文献 +^^^^^^^^^^^^^ + +[1] R. M. Neal, Statistics and Computing **11**, 125-139 (2001). + +[2] K. Hukushima and Y. Iba, AIP Conf. Proc. **690**, 200 (2003). + +[3] J. Machta, PRE **82**, 026704 (2010). diff --git a/manual/v3.0.0/ja/_sources/contact.rst.txt b/manual/v3.0.0/ja/_sources/contact.rst.txt new file mode 100644 index 00000000..1aaa5ae7 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/contact.rst.txt @@ -0,0 +1,22 @@ +お問い合わせ +========================================= + +ODAT-SE に関するお問い合わせはこちらにお寄せください。 + +- バグ報告 + + ODAT-SE のバグ関連の報告は `GitHubのIssues `_ で受け付けています。 + + バグを早期に解決するため、報告時には次のガイドラインに従ってください。 + + - 使用している ODAT-SE のバージョンを指定してください。 + + - インストールに問題がある場合には、使用しているオペレーティングシステムとコンパイラの情報についてお知らせください。 + + - 実行に問題が生じた場合は、実行に使用した入力ファイルとその出力を記載してください。 + +- その他 + + 研究に関連するトピックなどGitHubのIssuesで相談しづらいことを問い合わせる際には、以下の連絡先にコンタクトをしてください。 + + E-mail: ``2dmat-dev__at__issp.u-tokyo.ac.jp`` (_at_を@に変更してください) diff --git a/manual/v3.0.0/ja/_sources/customize/algorithm.rst.txt b/manual/v3.0.0/ja/_sources/customize/algorithm.rst.txt new file mode 100644 index 00000000..73af2277 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/customize/algorithm.rst.txt @@ -0,0 +1,184 @@ +``Algorithm`` の定義 +================================ + +``Algorithm`` クラスは ``odatse.algorithm.AlgorithmBase`` を継承したクラスとして定義します。 + +.. code-block:: python + + import odatse + + class Algorithm(odatse.algorithm.AlgorithmBase): + pass + + +``AlgorithmBase`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``AlgorithmBase`` クラスは次のメソッドを提供します。 + +- ``__init__(self, info: odatse.Info, runner: odatse.Runner = None)`` + + - ``info`` から ``Algorithm`` 共通の入力パラメータを読み取り、次のインスタンス変数を設定します。 + + - ``self.mpicomm: Optional[MPI.Comm]`` : ``MPI.COMM_WORLD`` + + - ``mpi4py`` の import に失敗した場合、 ``None`` が設定されます + + - ``self.mpisize: int`` : MPIプロセス数 + + - ``mpi4py`` の import に失敗した場合、 ``1`` が設定されます + + - ``self.mpirank: int`` : MPIランク + + - ``mpi4py`` の import に失敗した場合、 ``0`` が設定されます + + - ``self.rng: np.random.Generator`` : 擬似乱数生成器 + + - 擬似乱数の種について、詳細は :ref:`入力パラメータの [algorithm] セクション ` を参照してください + + - ``self.dimension: int`` : 探索パラメータ空間の次元 + - ``self.label_list: List[str]`` : 各パラメータの名前 + - ``self.root_dir: pathlib.Path`` : ルートディレクトリ + + - ``info.base["root_dir"]`` + + - ``self.output_dir: pathlib.Path`` : 出力ファイルを書き出すディレクトリ + + - ``info.base["root_dir"]`` + + - ``self.proc_dir: pathlib.Path`` : プロセスごとの作業用ディレクトリ + + - ``self.output_dir / str(self.mpirank)`` + - ディレクトリが存在しない場合、自動的に作成されます + - 各プロセスで最適化アルゴリズムはこのディレクトリで実行されます + + - ``self.timer: Dict[str, Dict]`` : 実行時間を保存するための辞書 + + - 空の辞書が3つ、 ``"prepare"``, ``"run"``, ``"post"`` という名前で定義されます + + - ``self.checkpoint`` : チェックポイント機能を有効/無効にする + + - ``self.checkpoint_steps`` + - ``self.checkpoint_interval`` + - ``self.checkpoint_file`` + + チェックポイント機能に関するパラメータが設定されます + + +- ``prepare(self) -> None`` + + - 最適化アルゴリズムの前処理をします + - ``self.run()`` の前に実行する必要があります + +- ``run(self) -> None`` + + - 最適化アルゴリズムを実行します + - 以下の処理を行います + + #. ``self.proc_dir`` に移動する + #. ``self.runner.prepare()`` を実行する + #. ``self._run()`` を実行する + #. ``self.runner.post()`` を実行する + #. 元のディレクトリに戻る + - ``self.prepare()`` の後に実行する必要があります + +- ``post(self) -> Dict`` + + - 最適化結果のファイル出力など、後処理を行います + - ``self.output_dir`` に移動し、 ``self._post()`` を実行した後、元のディレクトリに戻ります + - ``self.run()`` のあとに実行する必要があります + +- ``main(self, run_mode) -> Dict`` + + - ``prepare``, ``run``, ``post`` を順番に実行します + - それぞれの関数でかかった時間を計測し、結果をファイル出力します + - 実行モードを文字列型の引数で受け取ります。デフォルト値は ``initialize`` です。 + + - ``"initialize"``: 最初から実行 + - ``"resume"``: 中断した状態から再実行 + - ``"continue"``: 終了時の状態から継続実行 + + 乱数の初期化を指示する場合は、 ``"-resetrand"`` が追加されます。 + ``"continue"`` の動作はアルゴリズムによって変わります。 + + - 探索の結果を辞書形式で返します + + + +``Algorithm`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Algorithm`` は少なくとも次のメソッドを定義しなければなりません。 + +- ``__init__(self, info: odatse.Info, runner: odatse.Runner = None, domain = None)`` + + - ``info`` および ``runner`` 引数はそのまま基底クラスのコンストラクタに転送してください + + - ``super().__init__(info=info, runner=runner)`` + + - 入力パラメータである ``info`` から必要な設定を読み取り、保存してください + + - ``domain`` が指定されている場合は、探索領域を ``domain`` から取得します。 + 指定されていない場合は ``odatse.domain.Region(info)`` (探索領域が連続的な場合) または ``odatse.domain.MeshGrid(info)`` (離散的な場合) を用いて ``info`` から作成します。 + +- ``_prepare(self) -> None`` + + - 最適化アルゴリズムの前処理を記述します + +- ``_run(self) -> None`` + + - 最適化アルゴリズムを記述します + - 探索パラメータ ``x`` から対応する目的関数の値 ``f(x)`` を得るには、次のように Runner クラスのメソッドを呼び出します。 + + .. code-block:: python + + args = (step, set) + fx = self.runner.submit(x, args) + +- ``_post(self) -> Dict`` + + - 最適化アルゴリズムの後処理を記述します + - 探索の結果を辞書形式で返します + + +``Domain`` の定義 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +探索領域を記述する 2種類のクラスが用意されています。 + +``Region`` クラス +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +連続的なパラメータ空間を定義するためのヘルパークラスです。 + +- コンストラクタ引数は ``Info`` または ``param=`` にdict形式のパラメータを取ります。 + + - ``Info`` 型の引数の場合、 ``Info.algorithm.param`` から探索範囲の最小値・最大値・単位や初期値を取得します。 + + - dict 型の引数の場合は ``Info.algorithm.param`` 相当の内容を辞書形式で受け取ります。 + + - 詳細は :ref:`min_search の入力ファイル ` を参照してください。 + +- ``initialize(self, rng, limitation, num_walkers)`` を呼んで初期値の設定を行います。引数は乱数発生器 ``rng``, 制約条件 ``limitation``, walker の数 ``num_walkers`` です。 + + +``MeshGrid`` クラス +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +離散的的なパラメータ空間を定義するためのヘルパークラスです。 + +- コンストラクタ引数は ``Info`` または ``param=`` にdict形式のパラメータを取ります。 + + - ``Info`` 型の引数の場合、 ``Info.algorithm.param`` から探索範囲の最小値・最大値・単位や初期値を取得します。 + + - dict 型の引数の場合は ``Info.algorithm.param`` 相当の内容を辞書形式で受け取ります。 + + - 詳細は :ref:`mapper の入力ファイル ` を参照してください + +- ``do_split(self)`` メソッドは、候補点の集合を分割して各MPIランクに配分します。 + +- 入出力について + + - ``from_file(cls, path)`` クラスメソッドは、 ``path`` からメッシュデータを読み込んで ``MeshGrid`` クラスのインスタンスを作成します。 + + - ``store_file(self, path)`` メソッドは、メッシュの情報を ``path`` のファイルに書き出します。 diff --git a/manual/v3.0.0/ja/_sources/customize/common.rst.txt b/manual/v3.0.0/ja/_sources/customize/common.rst.txt new file mode 100644 index 00000000..53edce3f --- /dev/null +++ b/manual/v3.0.0/ja/_sources/customize/common.rst.txt @@ -0,0 +1,111 @@ +共通事項 +================================ + +``Solver`` と ``Algorithm`` に共通する事柄について説明します。 + +``odatse.Info`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +入力パラメータを扱うためのクラスです。 +インスタンス変数として次の4つの ``dict`` を持ちます。 + +- ``base`` + + - ディレクトリ情報など、プログラム全体で共通するパラメータ + +- ``solver`` + + - ``Solver`` が用いる入力パラメータ + +- ``algorithm`` + + - ``Algorithm`` が用いる入力パラメータ + +- ``runner`` + + - ``Runner`` が用いる入力パラメータ + + +``Info`` は ``base``, ``solver``, ``algorithm``, ``runner`` の4つのキー(省略可)を持つ ``dict`` を渡して初期化できます。また、クラスメソッド ``from_file`` に TOML形式の入力ファイルへのパスを渡して作成することもできます。 + + +``base`` について +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +要素として計算のルートディレクトリ ``root_dir`` と出力のルートディレクトリ ``output_dir`` が自動で設定されます + +- ルートディレクトリ ``root_dir`` + + - デフォルトはカレントディレクトリ ``"."`` です + - 絶対パスに変換されたものがあらためて ``root_dir`` に設定されます + - 先頭の ``~`` はホームディレクトリに展開されます + - 具体的には次のコードが実行されます + + .. code-block:: python + + p = pathlib.Path(base.get("root_dir", ".")) + base["root_dir"] = p.expanduser().absolute() + +- 出力ディレクトリ ``output_dir`` + + - 先頭の ``~`` はホームディレクトリに展開されます + - 絶対パスが設定されていた場合はそのまま設定されます + - 相対パスが設定されていた場合、 ``root_dir`` を起点とした相対パスとして解釈されます + - デフォルトは ``"."`` 、つまり ``root_dir`` と同一ディレクトリです + - 具体的には次のコードが実行されます + + .. code-block:: python + + p = pathlib.Path(base.get("work_dir", ".")) + p = p.expanduser() + base["work_dir"] = base["root_dir"] / p + + +``odatse.Runner`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Runner`` は ``Algorithm`` と ``Solver`` とをつなげるためのクラスです。 +コンストラクタ引数として ``Solver`` のインスタンス、 ``Info`` のインスタンス、パラメータの変換を記述する ``Mapping`` のインスタンス、制約条件を記述する ``Limitation`` のインスタンスを取ります。 +``Mapping`` のインスタンスを省略した場合は変換しない ``TrivialMapping`` が仮定されます。 +``Limitation`` のインスタンスを省略した場合は、制約を課さない ``Unlimited`` が仮定されます。 + +``submit(self, x: np.ndarray, args: Tuple[int,int]) -> float`` メソッドは、探索パラメータ ``x`` とオプションパラメータ ``args`` に対してソルバーを実行し、結果として目的関数の値 ``f(x)`` を返します。 +関数を評価する際に ``Limitation`` のインスタンスを用いて探索パラメータ ``x`` が制約を満たしているかを確認します。次に ``Mapping`` のインスタンスを用いて ``x`` から実際にソルバーが使う入力 ``y = mapping(x)`` を得ます。 + +その他、 ``Runner`` で使われる ``info`` の詳細は :doc:`../input` を参照してください。 + + +``odatse.Mapping`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Mapping`` は逆問題解析アルゴリズムの探索パラメータから順問題ソルバーの変数へのマッピングを記述するクラスです。 ``__call__(self, x: np.ndarray) -> np.ndarray`` メソッドを持つ関数オブジェクトとして定義します。 +現在は自明な変換 ``TrivialMapping`` とアフィン写像 ``Affine`` のクラスが定義されています。 + +``TrivialMapping`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +自明なマッピング :math:`x\to x` (変換しない)を与えるクラスです。 +Runner クラスの引数のデフォルト値となります。 + +``Affine`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +アフィン変換 :math:`x \to y=Ax+b` を与えるクラスです。 +要素 ``A``, ``b`` はコンストラクタの引数に指定するか、 ``from_dict`` クラスメソッドに辞書の形式で与えます。 +ODAT-SEの入力ファイルに指定する場合、パラメータの指定方法は「入力ファイル」の mapping セクションを参照してください。 + + +``odatse.Limitation`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Limitation`` は逆問題解析アルゴリズムで探索する :math:`N` 次元のパラメータ :math:`x` に課す制約条件を与えるクラスです。 ``judge(self, x: np.ndarray) -> bool`` のメソッドを持つクラスとして定義します。 +現在は制約なし ``Unlimited`` と線形不等式制約 ``Inequality`` のクラスが定義されています。 + +``Unlimited`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +制約条件を課さないというクラスです。 ``judge`` メソッドは常に ``True`` を返します。 +Runner クラスの引数のデフォルト値となります。 + +``Inequality`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:math:`N` 次元の探索パラメータ :math:`x` に対して、 :math:`M` 行 :math:`N` 列の行列 :math:`A` と :math:`M` 次元のベクトル :math:`b` で与えられる :math:`M` 個の制約条件 :math:`A x + b > 0` を課すクラスです。 + +要素 ``A``, ``b`` はコンストラクタの引数に指定するか、 ``from_dict`` クラスメソッドに辞書の形式で与えます。 +ODAT-SEの入力ファイルに指定する場合、パラメータの指定方法は「入力ファイル」の limitation セクションを参照してください。 diff --git a/manual/v3.0.0/ja/_sources/customize/index.rst.txt b/manual/v3.0.0/ja/_sources/customize/index.rst.txt new file mode 100644 index 00000000..94dd700d --- /dev/null +++ b/manual/v3.0.0/ja/_sources/customize/index.rst.txt @@ -0,0 +1,20 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +(開発者向け)ユーザー定義アルゴリズム・ソルバー +================================================= + +本ソフトウェアは、順問題のためのソルバー ``Solver`` と最適化のためのアルゴリズム ``Algorithm`` を組み合わせることで全体の逆問題を解きます。 +``Solver`` と ``Algorithm`` はすでに定義済みのものがいくつかありますが、これらを自分で定義することで、適用範囲を広げられます。 +本章では、 ``Solver`` や ``Algorithm`` を定義する方法およびこれらを使用する方法を解説します。 + + +.. toctree:: + :maxdepth: 1 + + common + solver + algorithm + usage diff --git a/manual/v3.0.0/ja/_sources/customize/solver.rst.txt b/manual/v3.0.0/ja/_sources/customize/solver.rst.txt new file mode 100644 index 00000000..dfff62bc --- /dev/null +++ b/manual/v3.0.0/ja/_sources/customize/solver.rst.txt @@ -0,0 +1,62 @@ +``Solver`` の定義 +================================ + +順問題を記述する ``Solver`` は、入力変数に対して目的関数の値を返す ``evaluate`` メソッドを持つクラスとして以下のように定義します。 + +- ``Solver`` クラスは ``odatse.solver.SolverBase`` を継承するクラスとします。 + + .. code-block:: python + + import odatse + + class Solver(odatse.solver.SolverBase): + pass + +- コンストラクタ + + コンストラクタは ``Info`` クラスのメソッドを引数としてとります。 + + .. code-block:: python + + def __init__(self, info: odatse.Info): + super().__init__(info) + ... + + 必ず ``info`` を引数として基底クラスのコンストラクタを呼び出してください。 + 基底クラスのコンストラクタでは、次のインスタンス変数が設定されます。 + + - ``self.root_dir`` はルートディレクトリです。 ``info.base["root_dir"]`` から取得され、 ``odatse`` を実行するディレクトリになります。外部プログラムやデータファイルなどを参照する際に起点として利用できます。 + + - ``self.output_dir`` は出力ファイルを書き出すディレクトリです。 ``info.base["output_dir"]`` から取得されます。通例、MPI並列の場合は各ランクからのデータを集約した結果を出力します。 + + - ``self.proc_dir`` はプロセスごとの作業用ディレクトリです。 ``output_dir / str(self.mpirank)`` が設定されます。 + ソルバーの ``evaluate`` メソッドは ``proc_dir`` をカレントディレクトリとして Runner から呼び出され、MPIプロセスごとの中間結果などを出力します。 + MPIを使用しない場合もランク番号を0として扱います。 + + Solver 固有のパラメータは ``info`` の ``solver`` フィールドから取得します。必要な設定を読み取って保存します。 + + +- ``evaluate`` メソッド + + .. code-block:: python + + def evaluate(self, x, args=(), nprocs=1, nthreads=1) -> float: + pass + + 入力変数に対して目的変数の値を返すメソッドです。以下の引数を取ります。 + + - ``x: np.ndarray`` + + 入力変数を numpy.ndarray 型の :math:`N` 次元ベクトルとして受け取ります。 + + - ``args: Tuple = ()`` + + Algorithm から渡される追加の引数で、step数と set番号からなる Tuple です。step数は Monte Carlo のステップ数や、グリッド探索のグリッド点のインデックスです。set番号は n巡目を表します。 + + - ``nprocs: int = 1`` + + - ``nthreads: int = 1`` + + ソルバーを MPI並列・スレッド並列で実行する際のプロセス数・スレッド数を受け取ります。現在は ``procs=1``, ``nthreads=1`` のみ対応しています。 + + ``evaluate`` メソッドは、Float 型の目的関数の値を返します。 diff --git a/manual/v3.0.0/ja/_sources/customize/usage.rst.txt b/manual/v3.0.0/ja/_sources/customize/usage.rst.txt new file mode 100644 index 00000000..6bb6d3cc --- /dev/null +++ b/manual/v3.0.0/ja/_sources/customize/usage.rst.txt @@ -0,0 +1,46 @@ +実行方法 +================================ + +次のようなフローで最適化問題を実行できます。 +プログラム例にあるコメントの番号はフローの番号に対応しています。 + +1. ユーザ定義クラスを作成する + + - ODAT-SEで定義済みのクラスも利用可能です + +2. 入力パラメータ ``info: odatse.Info`` を作成する + + - ``Info`` クラスにはTOML形式の入力ファイルを読み込むクラスメソッドが用意されています。この他にも、dict形式でパラメータを用意して ``Info`` クラスのコンストラクタに渡して作成することができます。 + +3. ``solver: Solver``, ``runner: odatse.Runner``, ``algorithm: Algorithm`` を作成する + +4. ``algorithm.main()`` を実行する + + +プログラム例 + +.. code-block:: python + + import sys + import odatse + + # (1) + class Solver(odatse.solver.SolverBase): + # Define your solver + pass + + class Algorithm(odatse.algorithm.AlgorithmBase): + # Define your algorithm + pass + + # (2) + input_file = sys.argv[1] + info = odatse.Info.from_file(input_file) + + # (3) + solver = Solver(info) + runner = odatse.Runner(solver, info) + algorithm = Algorithm(info, runner) + + # (4) + result = algorithm.main() diff --git a/manual/v3.0.0/ja/_sources/index.rst.txt b/manual/v3.0.0/ja/_sources/index.rst.txt new file mode 100644 index 00000000..db7379c1 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/index.rst.txt @@ -0,0 +1,23 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to ODAT-SE documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + start + tutorial/index + input + output + algorithm/index + solver/index + tool + customize/index + acknowledgement + contact diff --git a/manual/v3.0.0/ja/_sources/input.rst.txt b/manual/v3.0.0/ja/_sources/input.rst.txt new file mode 100644 index 00000000..b5fc8c9c --- /dev/null +++ b/manual/v3.0.0/ja/_sources/input.rst.txt @@ -0,0 +1,320 @@ +入力ファイル +================================ + +ODAT-SE は入力ファイルの形式に `TOML `_ を採用しています。 +入力ファイルは次の4つのセクションから構成されます。 + +- ``base`` + + - ODAT-SE 全体のパラメータを指定します。 + +- ``solver`` + + - ``Solver`` のパラメータを指定します。 + +- ``algorithm`` + + - ``Algorithm`` のパラメータを指定します。 + +- ``runner`` + + - ``Runner`` のパラメータを指定します。 + +[``base``] セクション +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``dimension`` + + 形式: 整数型 + + 説明: 探索空間の次元(探索するパラメータの数) + +- ``root_dir`` + + 形式: string型 (default: プログラム実行時のディレクトリ) + + 説明: プログラムを実行する一番上のディレクトリ。 + 入力ファイルなどのパスはすべて ``root_dir`` を起点とします。 + +- ``output_dir`` + + 形式: string型 (default: プログラム実行時のディレクトリ) + + 説明: プログラムの実行結果を出力するディレクトリ名 + +[``solver``] セクション +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``name`` でソルバーの種類を決定します。各パラメータはソルバーごとに定義されています。 + +- ``name`` + + 形式: string型 + + 説明: ソルバーの名前。以下のソルバーが用意されています。 + + - ``analytical`` : 解析関数を与えるソルバー (主にテストに利用) + + 以下は別モジュールとして配布される2次元物質構造解析向けソルバーです。 + + - ``sim-trhepd-rheed`` : 反射高速(陽)電子回折(RHEED, TRHEPD)の強度計算をするためのソルバー + + - ``sxrd`` : 表面X線回折(SXRD)解析のためのソルバー + + - ``leed`` : 低速電子線回折(LEED)解析のためのソルバー + +- ``dimension`` + + 形式: 整数型 (default: ``base.dimension``) + + 説明: ソルバーが受け取る入力パラメータの数。 + + +各種ソルバーの詳細および入出力ファイルは :doc:`solver/index` を参照してください。 + +.. _input_algorithm: + +[``algorithm``] セクション +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``name`` でアルゴリズムの種類を決定します。各パラメータはアルゴリズムごとに定義されています。 + +- ``name`` + + 形式: string型 + + 説明: アルゴリズムの名前。以下のアルゴリズムが用意されています。 + + - ``minsearch``: Nelder-Mead法による最小値探索 + + - ``mapper``: グリッド探索 + + - ``exchange``: レプリカ交換モンテカルロ法 + + - ``pamc``: ポピュレーションアニーリングモンテカルロ法 + + - ``bayes``: ベイズ最適化 + +- ``seed`` + + 形式: 整数値 + + 説明: 初期値のランダム生成やモンテカルロ更新などで用いる擬似乱数生成器の種を指定します。 + 各MPIプロセスに対して、 ``seed + mpi_rank * seed_delta`` の値が実際の種として用いられます。 + 省略した場合は `Numpy の規定の方法 `_ で初期化されます。 + + +- ``seed_delta`` + + 形式: 整数値 (default: 314159) + + 説明: 疑似乱数生成器の種について、MPI プロセスごとの値を計算する際に用いられます。 + 詳しくは ``seed`` を参照してください。 + +- ``checkpoint`` + + 形式: bool値 (default: false) + + 説明: 実行中および終了時の状態を定期的にファイルに出力します。実行が中断した場合に、チェックポイントから実行を再開できます。 + +- ``checkpoint_steps`` + + 形式: 整数値 (default: 16,777,216) + + 説明: 次のチェックポイントまでの繰り返し回数を指定します。繰り返し回数は、mapper の場合はグリッド点の数、bayes の場合は探索点の評価回数、モンテカルロ法(exchange, pamc) の場合は local update の回数です。 + デフォルト値は十分大きな数が設定されています。チェックポイント機能を有効にするには、 ``checkpoint_steps`` または ``checkpoint_interval`` の少なくとも一方を設定する必要があります。 + +- ``checkpoint_interval`` + + 形式: 実数値 (default: 31,104,000) + + 説明: 次のチェックポイントまでの経過時間を指定します。単位は秒です。 + デフォルト値は十分大きな数(360日)が設定されています。チェックポイント機能を有効にするには、 ``checkpoint_steps`` または ``checkpoint_interval`` の少なくとも一方を設定する必要があります。 + +- ``checkpoint_file`` + + 形式: 文字列 (default: ``"status.pickle"``) + + 説明: 実行中の状態を書き出すファイル名を指定します。ファイルはプロセスごとの出力ディレクトリに書き出されます。過去3世代分のファイルが .1, .2, .3 の suffix を付けて保存されます。 + + +各種アルゴリズムの詳細および入出力ファイルは :doc:`algorithm/index` を参照してください。 + + +[``runner``] セクション +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``Algorithm`` と ``Solver`` を橋渡しする要素である ``Runner`` の設定を記述します。 +サブセクションとして ``mapping``, ``limitation``, ``log`` を持ちます。 + + +[``runner.mapping``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Algorithm`` で探索している :math:`N` 次元のパラメータ :math:`x` から ``Solver`` で使う :math:`M` 次元のパラメータ :math:`y` への写像を定義します。 +:math:`N \ne M` となる場合には、 ``solver`` セクションにも ``dimension`` パラメータを指定してください。 + +現在はアフィン写像(線形写像+平行移動) :math:`y = Ax+b` が利用可能です。 + +- ``A`` + + 形式: リストのリスト、あるいは文字列 (default: []) + + 説明: :math:`N \times M` の変換行列 :math:`A` 。空のリストを渡した場合、単位行列とみなされます。 + 文字列として与える場合はそのまま行列の要素を空白および改行で区切って並べてください。 + +- ``b`` + + 形式: リスト、あるいは文字列 (default: []) + + 説明: :math:`M` 次元の並進移動ベクトル :math:`b` 。空のリストを渡した場合、ゼロベクトルとみなされます。 + 文字列として与える場合はそのままベクトルの要素を空白区切りで並べてください。 + +行列の指定方法について、例えば、 :: + + A = [[1,1], [0,1]] + +と :: + + A = """ + 1 1 + 0 1 + """ + +はともに + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right) + +を表します。 + +[``runner.limitation``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``Algorithm`` で探索している :math:`N` 次元のパラメータ :math:`x` に、制約条件を課すことが出来ます。 +``Algorithm`` ごとに定義する探索範囲(例：``exchange`` の ``min_list`` や ``max_list`` ) に加えて課すことが出来ます。 +現在は :math:`M` 行 :math:`N` 列の行列 :math:`A` と :math:`M` 次元の縦ベクトル :math:`b` から定義される :math:`Ax+b>0` の制約式が利用可能です。具体的に + +.. math:: + + A_{1,1} x_{1} + A_{1,2} x_{2} + &... + A_{1,N} x_{N} + b_{1} > 0\\ + A_{2,1} x_{1} + A_{2,2} x_{2} + &... + A_{2,N} x_{N} + b_{2} > 0\\ + &...\\ + A_{M,1} x_{1} + A_{M,2} x_{2} + &... + A_{M,N} x_{N} + b_{M} > 0 + +という制約をかけることができます。 +ここで :math:`M` は制約式の個数(任意)となります。 + +- ``co_a`` + + 形式: リストのリスト、あるいは文字列 (default: []) + + 説明: 制約式の行列 :math:`A` を設定します。 + + 行数は制約式数 :math:`M` 、列数は探索変数の数 :math:`N` である必要があります。 + + ``co_b`` を同時に定義する必要があります。 + +- ``co_b`` + + 形式: リストのリスト、あるいは文字列 (default: []) + + 説明: 制約式の縦ベクトル :math:`b` を設定します。 + + 次元数が制約式数 :math:`M` の縦ベクトルを設定する必要があります。 + + ``co_a`` を同時に定義する必要があります。 + +行列の指定方法について、[``mapping``] セクションと同様で、例えば、 :: + + A = [[1,1], [0,1]] + +と + +.. code-block:: toml + + A = """ + 1 1 + 0 1 + """ + +はともに + +.. math:: + + A = \left( + \begin{matrix} + 1 & 1 \\ + 0 & 1 + \end{matrix} + \right) + +を表します。また、 + +.. code-block:: toml + + co_b = [[0], [-1]] + +と + +.. code-block:: toml + + co_b = """0 -1""" + +と + +.. code-block:: toml + + co_b = """ + 0 + -1 + """ + +はともに + +.. math:: + + b = \left( + \begin{matrix} + 0 \\ + -1 + \end{matrix} + \right) + +を表します。 +``co_a`` と ``co_b`` のどちらも定義しない場合、制約式を課さずに探索します。 + +[``runner.log``] セクション +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +solver 呼び出しのlogging に関する設定です。 + +- ``filename`` + + 形式: 文字列 (default: "runner.log") + + 説明: ログファイルの名前。 + +- ``interval`` + + 形式: 整数 (default: 0) + + 説明: solver を interval 回呼ぶ毎にログが書き出されます。0以下の場合、ログ書き出しは行われません。 + +- ``write_result`` + + 形式: 真偽値 (default: false) + + 説明: solver からの出力を記録するかどうかを指定します。 + +- ``write_input`` + + 形式: 真偽値 (default: false) + + 説明: solver への入力を記録するかどうかを指定します。 diff --git a/manual/v3.0.0/ja/_sources/introduction.rst.txt b/manual/v3.0.0/ja/_sources/introduction.rst.txt new file mode 100644 index 00000000..38fadb69 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/introduction.rst.txt @@ -0,0 +1,105 @@ +はじめに +===================== + +ODAT-SEとは +---------------------- + +Open Data Analysis Tool for Science and Engineering (ODAT-SE)は、順問題ソルバーに対して探索アルゴリズムを適用して最適解を探すためのフレームワークです。Version 2までは2DMATという名称で開発されてきましたが、Version 3からは順問題ソルバーと探索アルゴリズムをモジュール化した汎用のデータ解析プラットフォームとして整備しています。 + +順問題ソルバーはユーザー自身で定義することが可能です。 +標準的な順問題ソルバーとしては2次元物質構造解析向け実験データ解析ソフトウェアが用意されています。 +順問題ソルバーでは原子位置などをパラメータとし得られたデータと実験データとのずれを損失関数として与えます。 +探索アルゴリズムを組み合わせ、この損失関数を最小化することで、最適なパラメータを推定します。 +現バージョンでは、順問題ソルバーとして量子ビーム回折実験の全反射高速陽電子回折法(Total-reflection high-energy positron diffraction: TRHEPD)[1, 2], 表面X線回折法(sxrd)[3], 低速電子線回折法(leed)[4]に対応しており、探索アルゴリズムはNelder-Mead法[5], グリッド型探索法[6], ベイズ最適化[7], レプリカ交換モンテカルロ法[8], ポピュレーションアニーリングモンテカルロ法[9, 10, 11]が実装されています。 + +今後は、本フレームワークをもとにより多くの順問題ソルバーおよび探索アルゴリズムを実装していく予定です。 + +[1] レビューとして， `Y．Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019) `_; +`兵頭俊夫，「全反射高速陽電子回折　(TRHEPD)による表面構造解析」，固体物理 53, 705 (2018) `_. + +[2] `T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022). `_ + +[3] `W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252, 5259 (2006). `_ + +[4] `M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993). `_ + +[5] `K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020). `_. + +[6] `K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series, 9, 011301 (2023). `_. + +[7] `Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022). `_ + +[8] `K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996). `_, `R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986) `_. + +[9] `R. M. Neal, Statistics and Computing 11, 125-139 (2001). `_ + +[10] `K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003). `_ + +[11] `J. Machta, Phys. Rev. E 82, 026704 (2010). `_ + +ライセンス +---------------------- +| 本ソフトウェアのプログラムパッケージおよびソースコード一式は + `Mozilla Public License version 2.0 (MPL-2.0) `_ に準じて配布されています。 + +Copyright (c) <2020-> The University of Tokyo. All rights reserved. + +本ソフトウェアは2020年度・2021年度・2024年度 東京大学物性研究所 ソフトウェア高度化プロジェクトの支援を受け開発されました。 +2DMAT / ODAT-SEを引用する際には以下の文献を引用してください。 + +`"Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures", Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, Computer Physics Communications 280, 108465 (2022) `_. + +BibTeX:: + + @article{MOTOYAMA2022108465, + title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures}, + journal = {Computer Physics Communications}, + volume = {280}, + pages = {108465}, + year = {2022}, + issn = {0010-4655}, + doi = {https://doi.org/10.1016/j.cpc.2022.108465}, + url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849}, + author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi} + } + + + +バージョン履歴 +---------------------- + +- ODAT-SE + + - v3.0.0 : 2024-11-25 + +- 2DMAT + + - v2.1.0 : 2022-04-08 + - v2.0.0 : 2022-01-17 + - v1.0.1 : 2021-04-15 + - v1.0.0 : 2021-03-12 + - v0.1.0 : 2021-02-08 + +主な開発者 +---------------------- +ODAT-SEは以下のメンバーで開発しています. + +- ODAT-SE v3.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 青山 龍美 (東京大学 物性研究所) + - 星　 健夫 (核融合科学研究所) + +- 2DMAT v2.0.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 岩本 晴道 (鳥取大学 大学院工学研究科) + - 星　 健夫 (鳥取大学 大学院工学研究科) + +- 2DMAT v0.1.0 - + + - 本山 裕一 (東京大学 物性研究所) + - 吉見 一慶 (東京大学 物性研究所) + - 星　 健夫 (鳥取大学 大学院工学研究科) diff --git a/manual/v3.0.0/ja/_sources/output.rst.txt b/manual/v3.0.0/ja/_sources/output.rst.txt new file mode 100644 index 00000000..ab798cae --- /dev/null +++ b/manual/v3.0.0/ja/_sources/output.rst.txt @@ -0,0 +1,61 @@ +出力ファイル +===================== + +各種 ``Solver``, ``Algorithm`` が出力するファイルについては、 :doc:`solver/index` および :doc:`algorithm/index` を参照してください。 + + +共通ファイル +~~~~~~~~~~~~~~~~~~ + +``time.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MPI のランク毎に計算にかかった総時間を出力します。 +各ランクのサブフォルダ以下に出力されます。 +計算の前処理にかかった時間、計算にかかった時間、計算の後処理にかかった時間について、 +``prepare`` , ``run`` , ``post`` のセクションごとに記載されます。 + +以下、出力例です。 + +.. code-block:: + + #prepare + total = 0.007259890999989693 + #run + total = 1.3493346729999303 + - file_CM = 0.0009563499997966574 + - submit = 1.3224223930001244 + #post + total = 0.000595873999941432 + + +``runner.log`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MPI のランクごとに、ソルバー呼び出しに関するログ情報を出力します。 +各ランクのサブフォルダ以下に出力されます。 +入力で ``runner.log.interval`` パラメータが正の整数の時のみ出力されます。 + +- 1列目がソルバー呼び出しの通し番号、 +- 2列目が前回呼び出しからの経過時間、 +- 3列目が計算開始からの経過時間 + +.. code-block:: + + # $1: num_calls + # $2: elapsed_time_from_last_call + # $3: elapsed_time_from_start + + 1 0.0010826379999999691 0.0010826379999999691 + 2 6.96760000000185e-05 0.0011523139999999876 + 3 9.67080000000009e-05 0.0012490219999999885 + 4 0.00011765699999999324 0.0013666789999999818 + 5 4.965899999997969e-05 0.0014163379999999615 + 6 8.666900000003919e-05 0.0015030070000000006 + ... + + +``status.pickle`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``algorithm.checkpoint`` が true の場合、MPI のランクごとに実行中の状態を出力します。 +各ランクのサブフォルダ以下に出力されます。実行を再開する場合に読み込まれます。 +ファイルの内容はアルゴリズムに依ります。 + diff --git a/manual/v3.0.0/ja/_sources/solver/analytical.rst.txt b/manual/v3.0.0/ja/_sources/solver/analytical.rst.txt new file mode 100644 index 00000000..42f7e400 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/solver/analytical.rst.txt @@ -0,0 +1,56 @@ +``analytical`` ソルバー +************************ + +``analytical`` は探索アルゴリズムの性能評価を目的とした、 +定義済みのベンチマーク関数 :math:`f(x)` を計算する ``Solver`` です。 + +入力パラメータ +~~~~~~~~~~~~~~~~~~~~~~~~ + +``solver`` セクション以下の ``funtion_name`` パラメータで用いる関数を指定します。 + +- ``function_name`` + + 形式: string型 + + 説明: 関数名。以下の関数が選べます。 + + - ``quadratics`` + + - 二次形式 + + .. math:: + + f(\vec{x}) = \sum_{i=1}^N x_i^2 + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + + - ``rosenbrock`` + + - `Rosenbrock 関数 `_ + + .. math:: + + f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right] + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)` + + - ``ackley`` + + - `Ackley 関数 `_ + + .. math:: + + f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right] + + - 最適値は :math:`f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)` + + - ``himmerblau`` + + - `Himmerblau 関数 `_ + + .. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + + - 最適値は :math:`f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0` diff --git a/manual/v3.0.0/ja/_sources/solver/index.rst.txt b/manual/v3.0.0/ja/_sources/solver/index.rst.txt new file mode 100644 index 00000000..50a72851 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/solver/index.rst.txt @@ -0,0 +1,19 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +順問題ソルバー +=============== + +順問題ソルバー ``Solver`` は探索パラメータ :math:`x` から最適化したい :math:`f(x)` を計算します。 + +.. toctree:: + :maxdepth: 1 + + analytical + +.. + sim-trhepd-rheed + sxrd + leed diff --git a/manual/v3.0.0/ja/_sources/start.rst.txt b/manual/v3.0.0/ja/_sources/start.rst.txt new file mode 100644 index 00000000..867aa025 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/start.rst.txt @@ -0,0 +1,85 @@ +ODAT-SE のインストール +================================ + +実行環境・必要なパッケージ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- python 3.9 以上 + + - 必要なpythonパッケージ + + - tomli (>= 1.2) + - numpy (>= 1.14) + + - Optional なパッケージ + + - mpi4py (グリッド探索利用時) + - scipy (Nelder-Mead法利用時) + - physbo (ベイズ最適化利用時, ver. 2.0以上) + +ダウンロード・インストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +下記に示す方法で、 ``ODAT-SE`` python パッケージと ``odatse`` コマンドがインストールできます。 + +- PyPI からのインストール(推奨) + + - ``python3 -m pip install ODAT-SE`` + + - ``--user`` オプションをつけるとローカル (``$HOME/.local``) にインストールできます + + - ``ODAT-SE[all]`` とすると Optional なパッケージも同時にインストールします + +- ソースコードからのインストール + + 1. ``git clone https://github.com/issp-center-dev/ODAT-SE`` + 2. ``python3 -m pip install ./ODAT-SE`` + + - ``pip`` のバージョンは 19 以上が必要です (``python3 -m pip install -U pip`` で更新可能) + +- サンプルファイルのダウンロード + + - サンプルファイルはソースコードに同梱されています。 + - ``git clone https://github.com/issp-center-dev/ODAT-SE`` + + +実行方法 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``odatse`` コマンドは定義済みの最適化アルゴリズム ``Algorithm`` と順問題ソルバー ``Solver`` の組み合わせで解析を行います。 + +.. code-block:: bash + + $ odatse input.toml + +定義済みの ``Algorithm`` については :doc:`algorithm/index` を、 +``Solver`` については :doc:`solver/index` を参照してください。 + +2次元物質構造解析向け実験データ解析の順問題ソルバーは独立なパッケージとして提供されています。 +これらの解析を行う場合は別途パッケージと必要なソフトウェアをインストールしてください。 +現在は以下の順問題ソルバーが用意されています。 + +- 全反射高速陽電子回折 (TRHEPD) -- odatse-STR パッケージ + +- 表面X線回折 (SXRD) -- odatse-SXRD パッケージ + +- 低速電子線回折 (LEED) -- odatse-LEED パッケージ + +``Algorithm`` や ``Solver`` をユーザーが準備する場合は、 ``ODAT-SE`` パッケージを利用します。 +詳しくは :doc:`customize/index` を参照してください。 + +なお、 プログラムを改造する場合など、 ``odatse`` コマンドをインストールせずに直接実行することも可能です。 +``src/odatse_main.py`` を利用してください。 + +.. code-block:: + + $ python3 src/odatse_main.py input.toml + + +アンインストール +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ODAT-SE モジュールをアンインストールするには、以下のコマンドを実行します。 + +.. code-block:: bash + + $ python3 -m pip uninstall ODAT-SE diff --git a/manual/v3.0.0/ja/_sources/tool.rst.txt b/manual/v3.0.0/ja/_sources/tool.rst.txt new file mode 100644 index 00000000..dfa11c27 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tool.rst.txt @@ -0,0 +1,59 @@ +関連ツール +===================== + +``odatse_neighborlist`` +***************************** + +離散空間をモンテカルロ探索する場合に使用する近傍リスト定義ファイルを +メッシュ定義ファイルから生成するツールです。 + +``pip`` でインストールした場合は ``odatse`` と同様に ``bin`` 以下に ``odatse_neighborlist`` という名前でインストールされます。 +もしくは、ディレクトリ中の ``src/odatse_neighborlist.py`` を直接実行することも可能です。 + +使い方 +~~~~~~~~~~~~~~~~ + +引数としてメッシュ定義ファイルを渡します。 +生成される近傍リスト定義ファイルの名前は ``-o`` オプションで指定可能です。 + +.. code-block:: bash + + $ odatse_neighborlist -o neighborlist.txt MeshData.txt + + +次のオプションが利用できます。 + +- ``-o output`` or ``--output output`` + + - 出力ファイル名 (default: ``neighborlist.txt``) + +- ``-u "unit1 unit2..."`` or ``--unit "unit1 unit2"`` + + - 各次元の長さスケール (default: すべて 1.0) + + - 空間次元の数だけ値を空白区切りで並べ、全体を引用符でくくってください + + - 各座標はあらかじめこれらの長さスケールで除算されます + +- ``-r radius`` or ``--radius radius`` + + - 近傍とみなされるユークリッド距離 (default: 1.0) + - 距離は ``-u`` で除されたあとの座標に対して計算されます + +- ``-q`` or ``--quiet`` + + - 進捗バーを表示しません + - なお、進捗バーの表示には ``tqdm`` python パッケージが必要です + +- ``--allow-selfloop`` + + - 自分自身を隣接リストに含めます（自己ループ） + +- ``--check-allpairs`` + + - すべての点対に対して距離を計算します + - デバッグ用のオプションです + + +なお、 MPI を用いて計算を高速化できます。 + diff --git a/manual/v3.0.0/ja/_sources/tutorial/bayes.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/bayes.rst.txt new file mode 100644 index 00000000..68538eda --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/bayes.rst.txt @@ -0,0 +1,166 @@ +ベイズ最適化 +================================ + +ここでは、ベイズ最適化を行いて Himmelblau関数の最小化問題を解析する方法について説明します。 +ベイズ最適化には `PHYSBO `_ を用います。 +事前に PHYSBO パッケージをインストールしておきます。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/bayes`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +また、計算結果を可視化するために ``sample`` フォルダ内の ``plot_himmel.py`` を利用します。 + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` を作成します。記述方法の詳細については「入力ファイル」の項を参照してください。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [algorithm] + name = "bayes" + seed = 12345 + + [algorithm.param] + min_list = [-6.0, -6.0] + max_list = [ 6.0, 6.0] + num_list = [61, 61] + + [algorithm.bayes] + random_max_num_probes = 20 + bayes_max_num_probes = 40 + + +``[base]``, ``[solver]``, ``[runner]`` のセクションについては Nelder-Mead法による探索(``minsearch``)の場合と同じです。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定をします。 + +- ``name`` は使用するアルゴリズムの名前です。このチュートリアルでは、ベイズ最適化を用いた解析を行うので、 ``bayes`` を指定します。 + +- ``seed`` は乱数の初期値を指定します。 + +``[algorithm.param]`` セクションでは、探索するパラメータの範囲や初期値を指定します。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 + +- ``num_list`` はパラメータの各方向へのグリッド点の個数を指定します。 + +``[algorithm.bayes]`` セクションでは、ベイズ最適化に関するハイパーパラメータを指定します。 + +- ``random_max_num_probes`` はランダムサンプリングの回数を指定します。 + +- ``bayes_max_num_probes`` はベイズ最適化を行う回数を指定します。 + + +ここではデフォルト値を用いるため省略しましたが、その他のパラメータについて詳細は「入力ファイル」の章を参照してください。 + + +計算の実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、ODAT-SEパッケージをダウンロードしたディレクトリ直下にいることを仮定します。) + +.. code-block:: + + $ cd sample/analytical/bayes + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ python3 ../../../src/odatse_main.py input.toml | tee log.txt + +実行すると ``output`` ディレクトリの下に各ランクのフォルダが作成されます。 +以下の様な標準出力がされます。 + +.. code-block:: + + # parameter + random_max_num_probes = 10 + bayes_max_num_probes = 20 + score = TS + interval = 5 + num_rand_basis = 5000 + value_01 = 5.10000 + value_02 = 4.90000 + R-factor = 0.037237314010261195 + 0001-th step: f(x) = -0.037237 (action=150) + current best f(x) = -0.037237 (best action=150) + + value_01 = 4.30000 + value_02 = 3.50000 + + ... + +最初に設定したパラメータのリスト、そのあとに各ステップでの候補パラメータと、 +その時の関数値 ``f(x)`` が出力されます。 +また、その時点での一番良いスコアを持つグリッドインデックス (``action``)とその場合の ``f(x)`` と変数が出力されます。 +最終的に推定されたパラメータは、 ``output/BayesData.txt`` に出力されます。 + +今回の場合は + +.. code-block:: + + #step x1 x2 fx x1_action x2_action fx_action + 0 -2.4 -0.7999999999999998 113.2192 -2.4 -0.7999999999999998 113.2192 + 1 -2.4 -0.7999999999999998 113.2192 1.6000000000000005 4.600000000000001 263.12320000000045 + 2 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.8000000000000007 -0.39999999999999947 28.995199999999958 + 3 2.8000000000000007 -0.39999999999999947 28.995199999999958 4.800000000000001 5.800000000000001 1306.739200000001 + 4 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.3999999999999995 2.5999999999999996 44.16320000000003 + 5 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.200000000000001 -5.2 623.6672 + 6 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.1999999999999993 2.200000000000001 65.45919999999997 + 7 4.200000000000001 -1.7999999999999998 23.619200000000067 4.200000000000001 -1.7999999999999998 23.619200000000067 + 8 4.200000000000001 -1.7999999999999998 23.619200000000067 -2.5999999999999996 -0.1999999999999993 111.10720000000002 + 9 4.200000000000001 -1.7999999999999998 23.619200000000067 0.6000000000000005 0.8000000000000007 130.00319999999994 + 10 4.200000000000001 -1.7999999999999998 23.619200000000067 -0.5999999999999996 -0.5999999999999996 178.7552 + ... + 38 3.200000000000001 1.8000000000000007 1.3952000000000133 3.200000000000001 -1.3999999999999995 8.051199999999973 + 39 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.8 -3.0 3.433599999999999 + 40 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.0 -2.8 27.705600000000004 + 41 3.6000000000000014 -1.7999999999999998 0.051200000000003215 3.6000000000000014 -1.7999999999999998 0.051200000000003215 + 42 3.6000000000000014 -1.7999999999999998 0.051200000000003215 2.0 2.5999999999999996 22.457599999999996 + ... + +のように得られます。1列目にステップ数、2〜4列目にその時点での最高スコアを与える ``x1``, ``x2`` と ``f(x)`` が記載されます。 +続けて、そのステップで候補となった ``x1``, ``x2`` と ``f(x)`` が記載されます。 +今回の場合は41ステップ目で正しい解が得られていることがわかります。 + + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``output/BayesData.txt`` を参照すると、何ステップ目のパラメータが最小スコアを与えたかがわかります。 + +.. code-block:: + + $ python3 ../plot_himmel.py --xcol=1 --ycol=2 --format="-o" --output=output/res.pdf output/BayesData.txt + $ python3 ../plot_himmel.py --xcol=4 --ycol=5 --format="o" --output=output/actions.pdf output/BayesData.txt + +上記を実行すると ``output/actions.pdf`` と ``output/res.pdf`` が作成され、Himmelblau関数の関数値を表す等高線の上に、ベイズ最適化で評価したグリッド点と最小スコアを与える点の履歴がプロットされます。 + + +.. figure:: ../../../common/img/res_bayes_plot.* + :align: center + + ベイズ最適化で評価したグリッド点(左図)と最小スコアを与える点の履歴(右図) diff --git a/manual/v3.0.0/ja/_sources/tutorial/exchange.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/exchange.rst.txt new file mode 100644 index 00000000..688921c4 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/exchange.rst.txt @@ -0,0 +1,162 @@ +レプリカ交換モンテカルロ法による探索 +================================================================ + +ここでは、レプリカ交換モンテカルロ法を用いて Himmelblau関数の最小化問題を解析する方法について説明します。 +具体的な計算手順は ``minsearch`` の時と同様です。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/exchange`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` について説明します。記述方法の詳細については「入力ファイル」の項を参照してください。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [algorithm] + name = "exchange" + seed = 12345 + + [algorithm.param] + min_list = [3.0, 3.0] + max_list = [6.0, 6.0] + step_list = [0.3, 0.3] + + [algorithm.exchange] + Tmin = 0.01 + Tmax = 100.0 + numsteps = 10000 + numsteps_exchange = 100 + nreplica_per_proc = 20 + + +ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。 + +``[base]``, ``[solver]``, ``[runner]`` のセクションについては Nelder-Mead法による探索(``minsearch``)の場合と同じです。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定を行います。 + +- ``name`` は使用するアルゴリズムの名前です。このチュートリアルではレプリカ交換モンテカルロ法による解析を行うので、 ``exchange`` を指定します。 + +``[algorithm.param]`` セクションでは、探索する連続なパラメータ空間の設定を行います。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 + +- ``step_list`` はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。 + +``[algorithm.exchange]`` サブセクションは、レプリカ交換モンテカルロ法のハイパーパラメータを指定します。 + +- ``numstep`` はモンテカルロ更新の回数です。 + +- ``numsteps_exchange`` で指定した回数のモンテカルロ更新の後に、温度交換を試みます。 + +- ``Tmin``, ``Tmax`` はそれぞれ温度の下限・上限です。 + +- ``Tlogspace`` が ``true`` の場合、温度を対数空間で等分割します。 + +- ``nreplica_per_proc`` は 1つのMPIプロセスが受け持つレプリカの数を指定します。 + + +計算の実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、ODAT-SEパッケージをダウンロードしたディレクトリ直下にいることを仮定します。) + +.. code-block:: + + $ cd sample/analytical/exchange + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +ここではプロセス数4のMPI並列を用いた計算を行っています。 +OpenMPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 ``mpiexec`` コマンドに ``--oversubscribe`` オプションを追加してください。 + +実行すると、 ``output`` ディレクトリの下に各ランクのフォルダが作成され、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した ``trial.txt`` ファイルと、実際に採択されたパラメータを記した ``result.txt`` ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。 + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 0.01 170.0 0.0 0.0 + 0 1 0.01123654800138751 187.94429125133564 5.155393113805774 -2.203493345018569 + 0 2 0.012626001098748564 3.179380982615041 -3.7929742598748666 -3.5452766573635235 + 0 3 0.014187266741165962 108.25464277273859 0.8127003489802398 1.1465364357510186 + 0 4 0.01594159037455999 483.84183395038843 5.57417423682746 1.8381251624588506 + 0 5 0.01791284454622004 0.43633134370869153 2.9868796504069426 1.8428384502208246 + 0 6 0.020127853758499396 719.7992581349758 2.972577711255287 5.535680832873856 + 0 7 0.022616759492228647 452.4691017123836 -5.899340424701358 -4.722667479627368 + 0 8 0.025413430367026365 45.5355817998709 -2.4155554347674215 1.8769341969872393 + 0 9 0.028555923019901074 330.7972369561986 3.717750630491217 4.466110964691396 + 0 10 0.032086999973704504 552.0479484091458 5.575771168463163 2.684224163039442 + ... + +``best_result.txt`` に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。 + +.. code-block:: + + nprocs = 80 + rank = 3 + step = 8025 + walker = 17 + fx = 3.358076734724385e-06 + x1 = 2.9998063442504126 + x2 = 1.999754886043102 + +ODAT-SE の実装では1つのレプリカが様々な温度のサンプルを保持しています。各ランクフォルダにある ``result.txt`` には、各レプリカでサンプリングされたデータが記録されています。 +この全レプリカの結果から温度ごとのサンプルに整列し直したデータが ``output/result_T%.txt`` に出力されます。(``%`` は温度点のindex。) +1列目がステップ、2列めがランク、3列目が目的関数の値、4列目以降がパラメータです。 + +.. code-block:: + + # T = 0.014187266741165962 + 0 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 1 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 2 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 3 3 108.25464277273859 0.8127003489802398 1.1465364357510186 + 4 3 93.5034551820852 1.3377081691728905 0.8736706475438123 + 5 3 81.40963740872147 1.4541906604820898 1.0420053981467825 + ... + + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``result_T%.txt`` を図示することで ``f(x)`` の小さいパラメータがどこにあるかを推定することができます。 +以下のコマンドを入力すると 2次元パラメータ空間の図 ``res_T%.png`` が作成されます。 + +.. code-block:: + + $ python3 ../plot_himmel.py --xcol=3 --ycol=4 --skip=20 --format="o" --output=output/res_T0.png output/result_T0.txt + +作成された図を見ると、 ``f(x)`` の最小値を与える点の付近にサンプルが集中していることが分かります。温度Tのインデックスを変えると、高温ではサンプリング点が領域内に広く分布していること、温度を下げると極小点付近に集中することが見てとれます。 + +.. figure:: ../../../common/img/res_exchange.* + + 2次元パラメータ空間上のモンテカルロ法によるサンプリング点の分布。 :math:`T=\{35.02, 3.40, 0.33, 0.01\}` の場合。 diff --git a/manual/v3.0.0/ja/_sources/tutorial/index.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/index.rst.txt new file mode 100644 index 00000000..9615dd4c --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/index.rst.txt @@ -0,0 +1,46 @@ +.. 2dmat documentation master file, created by + sphinx-quickstart on Tue May 26 18:44:52 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +チュートリアル +================================== + +このチュートリアルでは、解析関数の最小化問題を例として、ODAT-SEによる逆問題解析の方法を説明します。 +ODAT-SEには、逆問題を解くためのアルゴリズムとして以下の5つの手法が用意されています。 + +- ``minsearch`` + + Nealder-Mead法 + +- ``mapper_mpi`` + + 与えられたパラメータの探索グリッドを全探索する + +- ``bayes`` + + ベイズ最適化 + +- ``exchange`` + + レプリカ交換モンテカルロ法 + +- ``pamc`` + + ポピュレーションアニーリング法 + +以下ではこれらのアルゴリズムを用いた実行方法を説明します。 +また、制約式を用いて探索範囲を制限できる ``[runner.limitation]`` セクションを使用した実行方法も説明しています。 +最後に、自分で順問題ソルバーを定義する簡単な例について説明します。 + +.. toctree:: + :maxdepth: 1 + + intro + minsearch + mapper + bayes + exchange + pamc + limitation + solver_simple diff --git a/manual/v3.0.0/ja/_sources/tutorial/intro.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/intro.rst.txt new file mode 100644 index 00000000..cbb93e2c --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/intro.rst.txt @@ -0,0 +1,19 @@ +解析関数の最小化問題 +================================ + +順問題ソルバーの例として ODAT-SE に含まれている Analytical ソルバーの中から Himmelblau関数の最小化問題を取り上げます。 +Himmelblau関数は次の表式で表される2変数関数で、複数の極小点を持ち、最適化アルゴリズムの性能評価に使われます。 + +.. math:: + + f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2 + +最小値 :math:`f(x,y)=0` を与える :math:`(x,y)` は :math:`(3.0, 2.0)`, :math:`(-2.805118, 3.131312)`, :math:`(-3.779310, -3.283186)`, :math:`(3.584428, -1.848126)` です。 + +.. figure:: ../../../common/img/plot_himmelblau.* + + Himmelblau関数の plot。 + + +[1] D. Himmelblau, Applied Nonlinear Programming, McGraw-Hill, 1972. + diff --git a/manual/v3.0.0/ja/_sources/tutorial/limitation.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/limitation.rst.txt new file mode 100644 index 00000000..f6fefa1f --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/limitation.rst.txt @@ -0,0 +1,204 @@ +制約式を適用したレプリカ交換モンテカルロ法による探索 +================================================================ + +ここでは、 ``[runner.limitation]`` セクションに設定できる制約式機能のチュートリアルを示します。 +例として、レプリカ交換モンテカルロ法を用いてHimmelblauの最小値を探索する計算に制約式を適用します。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/limitation`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``input.toml`` + + メインプログラムの入力ファイル。 + +- ``ref.txt`` + + 計算が正しく実行されたか確認するためのファイル (本チュートリアルを行うことで得られる ``best_result.txt`` の回答)。 + +- ``hist2d_limitation_sample.py`` + + 可視化のためのツール。 + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。 + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` について説明します。 +詳細については「入力ファイル」の章を参照してください。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "exchange" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + unit_list = [0.3, 0.3] + + [algorithm.exchange] + Tmin = 1.0 + Tmax = 100000.0 + numsteps = 10000 + numsteps_exchange = 100 + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.limitation] + co_a = [[1, -1],[1, 1]] + co_b = [[0], [-1]] + + +``[base]`` セクションはメインプログラム全体のパラメータです。 + +- ``dimension`` は最適化したい変数の個数です。今の場合は2つの変数の最適化を行うので、 ``2`` を指定します。 + +- ``output_dir`` は出力先のディレクトリを指定します。 + +``[algorithm]`` セクションでは、用いる探索アルゴリズムを設定します。 + +- ``name`` は使用するアルゴリズムの名前です。このチュートリアルでは交換モンテカルロ法を用いるので ``"exchange"`` を指定します。 + +- ``seed`` は擬似乱数生成器に与える乱数の種です。 + +``[algorithm.param]`` サブセクションは、最適化したいパラメータの範囲などを指定します。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 + +- ``unit_list`` はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。 + +``[algorithm.exchange]`` サブセクションは、交換モンテカルロ法のハイパーパラメータを指定します。 + +- ``numstep`` はモンテカルロ更新の回数です。 + +- ``numsteps_exchange`` で指定した回数のモンテカルロ更新の後に、温度交換を試みます。 + +- ``Tmin``, ``Tmax`` はそれぞれ温度の下限・上限です。 + +- ``Tlogspace`` が ``true`` の場合、温度を対数空間で等分割します。指定がない場合のデフォルト値は ``true`` です。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。 + +- ``name`` は使用するソルバーの名前です。このチュートリアルでは ``analytical`` ソルバーに含まれる解析関数の解析を行います。 + +- ``function_name`` は ``analytical`` ソルバー内の関数名を指定します。 + +``[runner]`` セクションの ``[runner.limitation]`` サブセクションで制約式を設定します。 +現在、制約式は :math:`N` 次元のパラメータ :math:`x` 、 :math:`M` 行 :math:`N` 列の行列 :math:`A` 、 +:math:`M` 次元の縦ベクトル :math:`b` から定義される :math:`Ax+b>0` の制約式が利用可能です。 +パラメータとしては、以下の項目が設定可能です。 + +- ``co_a`` は行列 :math:`A` を設定します。 + +- ``co_b`` は縦ベクトル :math:`b` を設定します。 + +パラメータの詳しい設定方法はマニュアル内「入力ファイル」項の「 [``limitation``] セクション」を参照してください。 +今回は + +.. math:: + + x_{1} - x_{2} > 0 \\ + x_{1} + x_{2} - 1 > 0 + +の制約式を課して実行しています。 + +計算の実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します。) + +.. code-block:: + + $ cd sample/analytical/limitation + +次に、メインプログラムを実行します。計算時間は通常のPCで20秒程度で終わります。 + +.. code-block:: + + $ mpiexec -np 10 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +ここではプロセス数10のMPI並列を用いた計算を行っています。 +Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 ``mpiexec`` コマンドに ``--oversubscribe`` オプションを追加してください。 + +実行すると、 ``output`` フォルダが生成され、その中に各ランクのフォルダが作成されます。 +更にその中には、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した ``trial.txt`` ファイルと、実際に採択されたパラメータを記した ``result.txt`` ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。 +以下は、 ``output/0/result.txt`` ファイルの冒頭部分です。 + +.. code-block:: + + # step walker T fx x1 x2 + 0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569 + 1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + 3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816 + ... + +最後に、 ``output/best_result.txt`` に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。 + +.. code-block:: + + nprocs = 10 + rank = 2 + step = 4523 + walker = 0 + fx = 0.00010188398524402734 + x1 = 3.584944906595298 + x2 = -1.8506985826548874 + +なお、一括計算するスクリプトとして ``do.sh`` を用意しています。 +``do.sh`` では ``best_result.txt`` と ``ref.txt`` の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。 + +.. code-block:: + + #!/bin/bash + + mpiexec -np 10 --oversubscribe python3 ../../../src/odatse_main.py input.toml + + echo diff output/best_result.txt ref.txt + res=0 + diff output/best_result.txt ref.txt || res=$? + if [ $res -eq 0 ]; then + echo TEST PASS + true + else + echo TEST FAILED: best_result.txt and ref.txt differ + false + fi + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``result.txt`` を図示して、制約式を満たした座標のみを探索しているかを確認します。 +以下のコマンドを実行すると2次元パラメータ空間の図が ``<実行日>_histogram`` フォルダ内に作成されます。 +生成されるヒストグラムは、burn-in期間として最初の1000ステップ分の探索を捨てたデータを使用しています。 + +.. code-block:: + + $ python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1 + +作成された図には2本の直線 :math:`x_{1} - x_{2} = 0`, :math:`x_{1} + x_{2} - 1 = 0` と探索結果(事後確率分布のヒストグラム)を図示しています。 +図を見ると :math:`x_{1} - x_{2} > 0`, :math:`x_{1} + x_{2} - 1 > 0` の範囲のみ探索をしていることが確認できます。 +以下に図の一部を掲載します。 + +.. figure:: ../../../common/img/res_limitation.* + + サンプルされたパラメータと確率分布。横軸は ``x1`` , 縦軸は ``x2`` を表す。 diff --git a/manual/v3.0.0/ja/_sources/tutorial/mapper.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/mapper.rst.txt new file mode 100644 index 00000000..a2f18324 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/mapper.rst.txt @@ -0,0 +1,137 @@ +グリッド型探索 +================================ + +ここでは、グリッド型探索を行い Himmelblau関数の最小化問題を解析する方法について説明します。 +グリッド型探索はMPI並列化に対応しています。具体的な計算手順は ``minsearch`` の場合と同様です。 +探索グリッドはパラメータを元にプログラム内部で生成します。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/mapper`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``plot_colormap_2d.py`` + + 計算結果を可視化するためのプログラム + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` について説明します。記述方法の詳細については「入力ファイル」の項を参照してください。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.log] + interval = 20 + + [algorithm] + name = "mapper" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + num_list = [31, 31] + +``[base]``, ``[solver]``, ``[runner]`` のセクションについては Nelder-Mead法による探索(``minsearch``)の場合と同じです。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定を行います。 + +- ``name`` は使用するアルゴリズムの名前です。このチュートリアルでは、グリッド探索による解析を行うので、 ``mapper`` を指定します。 + +``[algorithm.param]`` セクションで探索するパラメータのグリッドを指定します。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 + +- ``num_list`` はパラメータの各方向へのグリッド点の個数を指定します。 + +ここではデフォルト値を用いるため省略しましたが、その他のパラメータについて詳細は「入力ファイル」の章を参照してください。 + + +計算の実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、ODAT-SEパッケージをダウンロードしたディレクトリの直下にいることを仮定します。) + +.. code-block:: + + $ cd sample/analytical/mapper + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +ここではプロセス数4のMPI並列を用いた計算を行っています。 +実行すると ``output`` ディレクトリとその下に各ランクのフォルダが作成され、ランクごとの計算結果が出力されます。 +同時に、以下の様な出力が標準出力に書き出されます。 + +.. code-block:: + + Make ColorMap + Iteration : 1/240 + Iteration : 2/240 + Iteration : 3/240 + Iteration : 4/240 + Iteration : 5/240 + Iteration : 6/240 + Iteration : 7/240 + ... + +``x1``, ``x2`` に各メッシュでの候補パラメータと、その時の関数値が出力されます。 +最終的にグリッド上の全ての点で計算された関数値が ``output/ColorMap.txt`` に出力されます。 +今回の場合は、 + +.. code-block:: + + -6.000000 -6.000000 890.000000 + -5.600000 -6.000000 753.769600 + -5.200000 -6.000000 667.241600 + -4.800000 -6.000000 622.121600 + -4.400000 -6.000000 610.729600 + -4.000000 -6.000000 626.000000 + -3.600000 -6.000000 661.481600 + -3.200000 -6.000000 711.337600 + -2.800000 -6.000000 770.345600 + ... + +のような結果が得られ、 +1列目、2列目に ``x1``, ``x2`` の値、3列目に関数値が記載されます。 + + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``ColorMap.txt`` を図示することで、関数の値が小さいパラメータがどこにあるかを推定することができます。そのような 2次元パラメータ空間のプロットを作成するプログラムが ``plot_colormap_2d.py`` に用意されています。 + +.. code-block:: + + $ python3 plot_colormap_2d.py + +上記を実行すると ``ColorMapFig.png`` が作成され、Himmelblau関数の関数値を表す等高線の上に、各グリッド点で評価した関数値がカラーマップとしてプロットされます。 + +.. figure:: ../../../common/img/res_mapper.* + + グリッド型探索における2次元パラメータ空間上での関数値のカラーマップ。 + diff --git a/manual/v3.0.0/ja/_sources/tutorial/minsearch.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/minsearch.rst.txt new file mode 100644 index 00000000..8c338324 --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/minsearch.rst.txt @@ -0,0 +1,158 @@ +Nelder-Mead法による最適化 +==================================== + +ここでは、Nelder-Mead法を用いて Himmelblau関数の最小値を探索する方法について説明します。 +具体的な計算手順は以下の通りです。 + +1. 入力ファイルを用意する + + 入力パラメータをTOML形式で記述した入力ファイルを作成します。 + +2. メインプログラムを実行する + + ``src/odatse_main.py`` を用いて計算を実行し、最適化問題を解きます。 + + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/minsearch`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + +また、計算結果を可視化するために ``sample`` フォルダ内の ``plot_himmel.py`` を利用します。 + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` を作成します。記述方法の詳細については「入力ファイル」の項を参照してください。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.log] + interval = 20 + + [algorithm] + name = "minsearch" + seed = 12345 + + [algorithm.param] + min_list = [-6.0, -6.0] + max_list = [ 6.0, 6.0] + initial_list = [0, 0] + + +``[base]`` セクションではプログラム全体で利用するパラメータを設定します。 + +- ``dimension`` は最適化したい変数の個数です。Himmelblau関数は 2変数関数ですので、今の場合は ``2`` を指定します。 + +- ``output_dir`` は出力先のディレクトリを指定します。 + +``[solver]`` セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。 + +- ``name`` は使用するソルバーの名前です。このチュートリアルでは ``analytical`` ソルバーに含まれる解析関数の解析を行います。 + +- ``function_name`` は ``analytical`` ソルバー内の関数名を指定します。 + +``[runner]`` セクションでは、逆問題解析アルゴリズムからソルバーの呼び出しに関する設定を行います。 + +- ``[runner.log]`` の ``interval`` は、ログ出力の頻度を指定します。 ``interval`` 回の繰り返し毎にログを出力します。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定をします。 + +- ``name`` は使用するアルゴリズムの名前です。このチュートリアルでは、Nelder-Mead法 を用いた解析を行うので、 ``minsearch`` を指定します。 + +- ``seed`` は乱数の初期値を指定します。 + +``[algorithm.param]`` セクションでは、探索するパラメータの範囲や初期値を指定します。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 +- ``initial_list`` は初期値を指定します。 + +ここではデフォルト値を用いるため省略しましたが、その他のパラメータ、例えばNelder-Mead法で使用する収束判定などについては、``[algorithm]`` セクションで行うことが可能です。 +詳細については「入力ファイル」の章を参照してください。 + + +計算の実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下では、ODAT-SE パッケージをダウンロードしたディレクトリの直下にいることを仮定します。) + +.. code-block:: + + $ cd sample/analytical/minsearch + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ python3 ../../../src/odatse_main.py input.toml | tee log.txt + +実行すると、以下の様な出力がされます。 + +.. code-block:: + + Optimization terminated successfully. + Current function value: 0.000000 + Iterations: 40 + Function evaluations: 79 + iteration: 40 + len(allvecs): 41 + step: 0 + allvecs[step]: [0. 0.] + step: 1 + allvecs[step]: [0.375 0.375] + step: 2 + allvecs[step]: [0.0625 0.9375] + step: 3 + allvecs[step]: [0.65625 1.46875] + step: 4 + allvecs[step]: [0.328125 2.859375] + ... + +``x1``, ``x2`` に各ステップでの候補パラメータと、その時の関数値が出力されます。 +最終的に推定されたパラメータは ``output/res.dat`` に出力されます。今の場合、 + +.. code-block:: + + fx = 4.2278370361994904e-08 + x1 = 2.9999669562950175 + x2 = 1.9999973389336225 + +が得られ、最小値を与える解の一つが求められたことが分かります。 + + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nelder-Mead法による解の探索の経路は ``output/0/SimplexData.txt`` に出力されています。 +これをプロットするツールが ``sample/plot_himmel.py`` に用意されています。 + +.. code-block:: + + $ python3 ../plot_himmel.py --xcol=1 --ycol=2 --output=output/res.pdf output/0/SimplexData.txt + +上記を実行すると ``output/res.pdf`` が出力されます。 + +.. figure:: ../../../common/img/res_minsearch.* + + Nelder-Mead法を用いた Himmelblau 関数の最小値探索。黒線は Himmelblau関数の関数値を表す等高線、青色のシンボルは探索経路。 + +Himmelblau関数の関数値を表す等高線の上に Nelder-Mead法による探索の経路がプロットされます。初期値 ``(0, 0)`` からスタートして最小値を与える解の一つ ``(3, 2)`` に到達していることが分かります。 diff --git a/manual/v3.0.0/ja/_sources/tutorial/pamc.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/pamc.rst.txt new file mode 100644 index 00000000..d3af4d0c --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/pamc.rst.txt @@ -0,0 +1,173 @@ +ポピュレーションアニーリングによる探索 +================================================================ + +ここでは、ポピュレーションアニーリングを用いて Himmelblau関数の最小化問題を解析する方法について説明します。 +具体的な計算手順は ``minsearch`` の時と同様です。 + +サンプルファイルの場所 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サンプルファイルは ``sample/analytical/pamc`` にあります。 +フォルダには以下のファイルが格納されています。 + +- ``input.toml`` + + メインプログラムの入力ファイル + +- ``do.sh`` + + 本チュートリアルを一括計算するために準備されたスクリプト + + +入力ファイルの説明 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +メインプログラム用の入力ファイル ``input.toml`` について説明します。記述方法の詳細については「入力ファイル」の項を参照してください。 + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [solver] + name = "analytical" + function_name = "himmelblau" + + [runner] + [runner.log] + interval = 20 + + [algorithm] + name = "pamc" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + step_list = [0.1, 0.1] + + [algorithm.pamc] + Tmin = 1.0 + Tmax = 100.0 + Tnum = 21 + Tlogspace = true + numsteps_annealing = 100 + nreplica_per_proc = 100 + +ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。 + + +``[base]``, ``[solver]``, ``[runner]`` のセクションについては Nelder-Mead法による探索(``minsearch``)の場合と同じです。 + +``[algorithm]`` セクションでは、使用するアルゴリスムとその設定を行います。 + +- ``name`` は使用するアルゴリズムの名前です。このチュートリアルでは、ポピュレーションアニーリング法による解析を行うので、 ``pamc`` を指定します。 + +``[algorithm.param]`` セクションでは、探索する連続なパラメータ空間の設定を行います。 + +- ``min_list`` と ``max_list`` はそれぞれ探索範囲の最小値と最大値を指定します。 + +- ``step_list`` はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。 + +``[algorithm.pamc]`` セクションは、ポピュレーションアニーリングのハイパーパラメータを指定します。 + +- ``numsteps_annealing`` で指定した回数のモンテカルロ更新の後に、逆温度を増やします (温度を下げます)。 + +- ``bmin``, ``bmax`` はそれぞれ逆温度の下限・上限です。 + +- ``Tnum`` は計算する温度・逆温度の点数です。 + +- ``Tlogspace`` が ``true`` の場合、温度を対数空間で等分割します + +- ``nreplica_per_proc`` はMPIプロセスひとつが受け持つ計算レプリカの数です。 + + +計算の実行 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します。) + +.. code-block:: + + $ cd sample/analytical/pamc + +メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。 + +.. code-block:: + + $ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt + +ここではプロセス数4のMPI並列を用いた計算を行っています。 +OpenMPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 ``mpiexec`` コマンドに ``--oversubscribe`` オプションを追加してください。 + +実行すると、 ``output`` ディレクトリの下に各ランクのフォルダが作成され、温度ごとに、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した ``trial_TXXX.txt`` ファイル(``XXX`` は温度点の番号)と、実際に採択されたパラメータを記した ``result_TXXX.txt`` ファイル、さらにそれぞれを結合した ``trial.txt``, ``result.txt`` ファイルが生成されます。 +それぞれ書式は同じで、最初の2列がステップ数とプロセス内の walker (replica) 番号、次が(逆)温度、3列目が目的関数の値、4列目以降がパラメータです。 +最後の2 列は、 walker の重み (Neal-Jarzynski weight) と祖先(計算を開始したときのレプリカ)の番号です。 + +.. code-block:: + + # step walker T fx x1 x2 weight ancestor + 0 0 100.0 187.94429125133564 5.155393113805774 -2.203493345018569 1.0 0 + 0 1 100.0 3.179380982615041 -3.7929742598748666 -3.5452766573635235 1.0 1 + 0 2 100.0 108.25464277273859 0.8127003489802398 1.1465364357510186 1.0 2 + 0 3 100.0 483.84183395038843 5.57417423682746 1.8381251624588506 1.0 3 + 0 4 100.0 0.43633134370869153 2.9868796504069426 1.8428384502208246 1.0 4 + 0 5 100.0 719.7992581349758 2.972577711255287 5.535680832873856 1.0 5 + 0 6 100.0 452.4691017123836 -5.899340424701358 -4.722667479627368 1.0 6 + 0 7 100.0 45.5355817998709 -2.4155554347674215 1.8769341969872393 1.0 7 + 0 8 100.0 330.7972369561986 3.717750630491217 4.466110964691396 1.0 8 + 0 9 100.0 552.0479484091458 5.575771168463163 2.684224163039442 1.0 9 + 0 10 100.0 32.20027165958588 1.7097039347500953 2.609443449748964 1.0 10 + ... + +``output/best_result.txt`` に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。 + +.. code-block:: + + nprocs = 4 + rank = 3 + step = 1806 + walker = 74 + fx = 4.748689609377718e-06 + x1 = -2.805353724219707 + x2 = 3.131045687296453 + +最後に、 ``output/fx.txt`` には、各温度ごとの統計情報が記録されます。 + +.. code-block:: + + # $1: 1/T + # $2: mean of f(x) + # $3: standard error of f(x) + # $4: number of replicas + # $5: log(Z/Z0) + # $6: acceptance ratio + 0.01 130.39908953806298 6.023477428315198 400 0.0 0.9378 + 0.01258925411794167 83.6274790817115 3.83620542622489 400 -0.2971072297035158 0.930325 + 0.015848931924611134 60.25390522675298 2.73578884504734 400 -0.5426399088244793 0.940375 + 0.01995262314968879 47.20146188151557 2.3479083531465976 400 -0.7680892360649545 0.93715 + 0.025118864315095794 41.118822390166315 1.8214854089575818 400 -0.9862114670289625 0.9153 + ... + +1列目は温度・逆温度で、2・3列目は目的関数 :math:`f(x)` の期待値と標準誤差、4列目はレプリカの個数、5列目は分配関数の比の対数 :math:`\log(Z_n/Z_0)` (:math:`Z_0` は最初の温度点における分配関数)、6列目はモンテカルロ更新の採択率です。 + + +計算結果の可視化 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``result_T%.txt`` を図示することで ``f(x)`` の小さいパラメータがどこにあるかを推定することができます。 +以下のコマンドを入力すると2次元パラメータ空間の図 ``res_T%.png`` が作成されます。 +シンボルの色は目的関数の値に対応します。 + +.. code-block:: + + $ python3 plot_result_2dmap.py + +作成された図を見ると、 ``T`` を小さくするごとに ``f(x)`` の最小値を与える点の付近にサンプルが集中していることがわかります。 + +.. figure:: ../../../common/img/res_pamc.* + + サンプルされたパラメータ。横軸は ``x1`` , 縦軸は ``x2`` を、色は ``T`` (左図), ``f(x)`` (右図)を表す。 + diff --git a/manual/v3.0.0/ja/_sources/tutorial/solver_simple.rst.txt b/manual/v3.0.0/ja/_sources/tutorial/solver_simple.rst.txt new file mode 100644 index 00000000..75ca7ccc --- /dev/null +++ b/manual/v3.0.0/ja/_sources/tutorial/solver_simple.rst.txt @@ -0,0 +1,95 @@ +順問題ソルバーの追加 +================================ + +ベンチマーク関数ソルバー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ODAT-SEでは探索アルゴリズムのテストに利用できる順問題ソルバーとして ``analytical`` ソルバーを用意しています。 + +``analytical`` ソルバーを使うには、入力ファイルの ``[solver]`` セクションの ``name`` を ``"analytical"`` に設定し、 ``function_name`` パラメータを用いてベンチマーク関数 :math:`f(x)` を選択します。 +たとえば、 Himmelblau 関数を用いる場合には + +.. code-block:: toml + + [solver] + name = "analytical" + function_name = "himmelblau" + +とします。 +利用可能な関数の詳細は :doc:`analytical ソルバーのリファレンス <../solver/analytical>` を参照してください。 + +順問題ソルバーの追加 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ユーザ定義の順問題ソルバーを定義・解析する一番簡単な方法は、 ``analytical`` ソルバーに追加することです。 +ここでは例として、 `Booth関数 `_ + +.. math:: + + f(x,y) = (x+2y-7)^{2} + (2x+y-5)^{2} + +を追加してみましょう。(最小値は :math:`f(1,3) = 0`) + +そのためには、 ODAT-SEのソースコードをダウンロードし、ファイルを編集する必要があります。 +ダウンロード方法や、ソースコードからの実行方法などは、 :doc:`インストールページ <../start>` を参照してください。 + +``analytical`` ソルバーは ``src/odatse/solver/analytical.py`` に定義されているので、これを編集します。 + +まず、 ``booth`` 関数を定義します。 + +.. code-block:: python + + def booth(xs: np.ndarray) -> float: + """Booth function + + it has one global minimum f(xs) = 0 at xs = [1,3]. + """ + + if xs.shape[0] != 2: + raise RuntimeError( + f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one" + ) + return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2 + +つぎに、入力ファイルの ``solver.function_name`` パラメータで ``booth`` 関数を指定できるようにするために、``Solver`` クラスのコンストラクタ (``__init__``) 中の if 分岐に以下のコードを挿入します。 + +.. code-block:: python + + elif function_name == "booth": + self.set_function(booth) + +この改造した ``analytical`` ソルバーでは、 Booth 関数の最適化が行なえます。 +たとえばNelder-Mead 法による最適化は、以下の入力ファイル (``input.toml``) を + +.. code-block:: + + [base] + dimension = 2 + output_dir = "output" + + [algorithm] + name = "minsearch" + seed = 12345 + + [algorithm.param] + max_list = [6.0, 6.0] + min_list = [-6.0, -6.0] + initial_list = [0, 0] + + [solver] + name = "analytical" + function_name = "booth" + +``src/odatse_main.py`` に渡せば実行可能です。 + +.. code-block:: + + $ python3 src/odatse_main.py input.toml + + ... skipped ... + + Iterations: 38 + Function evaluations: 75 + Solution: + x1 = 1.0000128043523089 + x2 = 2.9999832920260863 diff --git a/manual/v3.0.0/ja/_static/alert_info_32.png b/manual/v3.0.0/ja/_static/alert_info_32.png new file mode 100644 index 00000000..ea4d1baf Binary files /dev/null and b/manual/v3.0.0/ja/_static/alert_info_32.png differ diff --git a/manual/v3.0.0/ja/_static/alert_warning_32.png b/manual/v3.0.0/ja/_static/alert_warning_32.png new file mode 100644 index 00000000..a687c3dc Binary files /dev/null and b/manual/v3.0.0/ja/_static/alert_warning_32.png differ diff --git a/manual/v3.0.0/ja/_static/basic.css b/manual/v3.0.0/ja/_static/basic.css new file mode 100644 index 00000000..944485b9 --- /dev/null +++ b/manual/v3.0.0/ja/_static/basic.css @@ -0,0 +1,914 @@ +/* + * Sphinx stylesheet -- basic theme. + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin-top: 10px; +} + +ul.search li { + padding: 5px 0; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 59em; + max-width: 70em; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/manual/v3.0.0/ja/_static/bg-page.png b/manual/v3.0.0/ja/_static/bg-page.png new file mode 100644 index 00000000..fe0a6dc8 Binary files /dev/null and b/manual/v3.0.0/ja/_static/bg-page.png differ diff --git a/manual/v3.0.0/ja/_static/bullet_orange.png b/manual/v3.0.0/ja/_static/bullet_orange.png new file mode 100644 index 00000000..1cb8097c Binary files /dev/null and b/manual/v3.0.0/ja/_static/bullet_orange.png differ diff --git a/manual/v3.0.0/ja/_static/doctools.js b/manual/v3.0.0/ja/_static/doctools.js new file mode 100644 index 00000000..0398ebb9 --- /dev/null +++ b/manual/v3.0.0/ja/_static/doctools.js @@ -0,0 +1,149 @@ +/* + * Base JavaScript utilities for all Sphinx HTML documentation. + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/manual/v3.0.0/ja/_static/documentation_options.js b/manual/v3.0.0/ja/_static/documentation_options.js new file mode 100644 index 00000000..3942a728 --- /dev/null +++ b/manual/v3.0.0/ja/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '3.0-dev', + LANGUAGE: 'ja', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/manual/v3.0.0/ja/_static/file.png b/manual/v3.0.0/ja/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/manual/v3.0.0/ja/_static/file.png differ diff --git a/manual/v3.0.0/ja/_static/haiku.css b/manual/v3.0.0/ja/_static/haiku.css new file mode 100644 index 00000000..8b2e7581 --- /dev/null +++ b/manual/v3.0.0/ja/_static/haiku.css @@ -0,0 +1,369 @@ +/* + * Sphinx stylesheet -- haiku theme. + * + * Adapted from https://haiku-os.org/docs/Haiku-doc.css. + * Original copyright message: + * + * Copyright 2008-2009, Haiku. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Francois Revol + * Stephan Assmus + * Braden Ewing + * Humdinger + * + */ + +@import url("basic.css"); + +html { + margin: 0px; + padding: 0px; + background: #FFF url(bg-page.png) top left repeat-x; +} + +body { + line-height: 1.5; + margin: auto; + padding: 0px; + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; + min-width: 59em; + max-width: 70em; + color: #333333; +} + +div.footer { + padding: 8px; + font-size: 11px; + text-align: center; + letter-spacing: 0.5px; +} + +/* link colors and text decoration */ + +a:link { + font-weight: bold; + text-decoration: none; + color: #dc3c01; +} + +a:visited { + font-weight: bold; + text-decoration: none; + color: #551a8b; +} + +a:hover, a:active { + text-decoration: underline; + color: #ff4500; +} + +/* Some headers act as anchors, don't give them a hover effect */ + +h1 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h2 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h3 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +h4 a:hover, a:active { + text-decoration: none; + color: #0c3762; +} + +a.headerlink { + color: #a7ce38; + padding-left: 5px; +} + +a.headerlink:hover { + color: #a7ce38; +} + +/* basic text elements */ + +div.content { + margin-top: 20px; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 50px; + font-size: 0.9em; +} + +/* heading and navigation */ + +div.header { + position: relative; + left: 0px; + top: 0px; + height: 85px; + /* background: #eeeeee; */ + padding: 0 40px; +} +div.header h1 { + font-size: 1.6em; + font-weight: normal; + letter-spacing: 1px; + color: #0c3762; + border: 0; + margin: 0; + padding-top: 15px; +} +div.header h1 a { + font-weight: normal; + color: #0c3762; +} +div.header h2 { + font-size: 1.3em; + font-weight: normal; + letter-spacing: 1px; + text-transform: uppercase; + color: #aaa; + border: 0; + margin-top: -3px; + padding: 0; +} + +div.header img.rightlogo { + float: right; +} + + +div.title { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-bottom: 25px; +} +div.topnav { + /* background: #e0e0e0; */ +} +div.topnav p { + margin-top: 0; + margin-left: 40px; + margin-right: 40px; + margin-bottom: 0px; + text-align: right; + font-size: 0.8em; +} +div.bottomnav { + background: #eeeeee; +} +div.bottomnav p { + margin-right: 40px; + text-align: right; + font-size: 0.8em; +} + +a.uplink { + font-weight: normal; +} + + +/* contents box */ + +table.index { + margin: 0px 0px 30px 30px; + padding: 1px; + border-width: 1px; + border-style: dotted; + border-color: #e0e0e0; +} +table.index tr.heading { + background-color: #e0e0e0; + text-align: center; + font-weight: bold; + font-size: 1.1em; +} +table.index tr.index { + background-color: #eeeeee; +} +table.index td { + padding: 5px 20px; +} + +table.index a:link, table.index a:visited { + font-weight: normal; + text-decoration: none; + color: #dc3c01; +} +table.index a:hover, table.index a:active { + text-decoration: underline; + color: #ff4500; +} + + +/* Haiku User Guide styles and layout */ + +/* Rounded corner boxes */ +/* Common declarations */ +div.admonition { + -webkit-border-radius: 10px; + -khtml-border-radius: 10px; + -moz-border-radius: 10px; + border-radius: 10px; + border-style: dotted; + border-width: thin; + border-color: #dcdcdc; + padding: 10px 15px 10px 15px; + margin-bottom: 15px; + margin-top: 15px; +} +div.note { + padding: 10px 15px 10px 80px; + background: #e4ffde url(alert_info_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.warning { + padding: 10px 15px 10px 80px; + background: #fffbc6 url(alert_warning_32.png) 15px 15px no-repeat; + min-height: 42px; +} +div.seealso { + background: #e4ffde; +} + +/* More layout and styles */ +h1 { + font-size: 1.3em; + font-weight: bold; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h2 { + font-size: 1.2em; + font-weight: normal; + color: #0c3762; + border-bottom: dotted thin #e0e0e0; + margin-top: 30px; +} + +h3 { + font-size: 1.1em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +h4 { + font-size: 1.0em; + font-weight: normal; + color: #0c3762; + margin-top: 30px; +} + +p { + text-align: justify; +} + +p.last { + margin-bottom: 0; +} + +ol { + padding-left: 20px; +} + +ul { + padding-left: 5px; + margin-top: 3px; +} + +li { + line-height: 1.3; +} + +div.content ul > li { + -moz-background-clip:border; + -moz-background-inline-policy:continuous; + -moz-background-origin:padding; + background: transparent url(bullet_orange.png) no-repeat scroll left 0.45em; + list-style-image: none; + list-style-type: none; + padding: 0 0 0 1.666em; + margin-bottom: 3px; +} + +td { + vertical-align: top; +} + +code { + background-color: #e2e2e2; + font-size: 1.0em; + font-family: monospace; +} + +pre { + border-color: #0c3762; + border-style: dotted; + border-width: thin; + margin: 0 0 12px 0; + padding: 0.8em; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +/* printer only pretty stuff */ +@media print { + .noprint { + display: none; + } + /* for acronyms we want their definitions inlined at print time */ + acronym[title]:after { + font-size: small; + content: " (" attr(title) ")"; + font-style: italic; + } + /* and not have mozilla dotted underline */ + acronym { + border: none; + } + div.topnav, div.bottomnav, div.header, table.index { + display: none; + } + div.content { + margin: 0px; + padding: 0px; + } + html { + background: #FFF; + } +} + +.viewcode-back { + font-family: "DejaVu Sans", Arial, Helvetica, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; + margin: -1px -10px; + padding: 0 12px; +} + +/* math display */ +div.math p { + text-align: center; +} \ No newline at end of file diff --git a/manual/v3.0.0/ja/_static/language_data.js b/manual/v3.0.0/ja/_static/language_data.js new file mode 100644 index 00000000..15e4a844 --- /dev/null +++ b/manual/v3.0.0/ja/_static/language_data.js @@ -0,0 +1,19 @@ +/* + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + */ + +var stopwords = []; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Dummy stemmer for languages without stemming rules. + */ +var Stemmer = function() { + this.stemWord = function(w) { + return w; + } +} + diff --git a/manual/v3.0.0/ja/_static/minus.png b/manual/v3.0.0/ja/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/manual/v3.0.0/ja/_static/minus.png differ diff --git a/manual/v3.0.0/ja/_static/plus.png b/manual/v3.0.0/ja/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/manual/v3.0.0/ja/_static/plus.png differ diff --git a/manual/v3.0.0/ja/_static/pygments.css b/manual/v3.0.0/ja/_static/pygments.css new file mode 100644 index 00000000..650b5270 --- /dev/null +++ b/manual/v3.0.0/ja/_static/pygments.css @@ -0,0 +1,72 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #ffffff; } +.highlight .c { color: #aaaaaa; font-style: italic } /* Comment */ +.highlight .err { color: #FF0000; background-color: #FFAAAA } /* Error */ +.highlight .k { color: #0000aa } /* Keyword */ +.highlight .ch { color: #aaaaaa; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #aaaaaa; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #4c8317 } /* Comment.Preproc */ +.highlight .cpf { color: #aaaaaa; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #aaaaaa; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #0000aa; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #aa0000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #aa0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00aa00 } /* Generic.Inserted */ +.highlight .go { color: #888888 } /* Generic.Output */ +.highlight .gp { color: #555555 } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #aa0000 } /* Generic.Traceback */ +.highlight .kc { color: #0000aa } /* Keyword.Constant */ +.highlight .kd { color: #0000aa } /* Keyword.Declaration */ +.highlight .kn { color: #0000aa } /* Keyword.Namespace */ +.highlight .kp { color: #0000aa } /* Keyword.Pseudo */ +.highlight .kr { color: #0000aa } /* Keyword.Reserved */ +.highlight .kt { color: #00aaaa } /* Keyword.Type */ +.highlight .m { color: #009999 } /* Literal.Number */ +.highlight .s { color: #aa5500 } /* Literal.String */ +.highlight .na { color: #1e90ff } /* Name.Attribute */ +.highlight .nb { color: #00aaaa } /* Name.Builtin */ +.highlight .nc { color: #00aa00; text-decoration: underline } /* Name.Class */ +.highlight .no { color: #aa0000 } /* Name.Constant */ +.highlight .nd { color: #888888 } /* Name.Decorator */ +.highlight .ni { color: #880000; font-weight: bold } /* Name.Entity */ +.highlight .nf { color: #00aa00 } /* Name.Function */ +.highlight .nn { color: #00aaaa; text-decoration: underline } /* Name.Namespace */ +.highlight .nt { color: #1e90ff; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #aa0000 } /* Name.Variable */ +.highlight .ow { color: #0000aa } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #009999 } /* Literal.Number.Bin */ +.highlight .mf { color: #009999 } /* Literal.Number.Float */ +.highlight .mh { color: #009999 } /* Literal.Number.Hex */ +.highlight .mi { color: #009999 } /* Literal.Number.Integer */ +.highlight .mo { color: #009999 } /* Literal.Number.Oct */ +.highlight .sa { color: #aa5500 } /* Literal.String.Affix */ +.highlight .sb { color: #aa5500 } /* Literal.String.Backtick */ +.highlight .sc { color: #aa5500 } /* Literal.String.Char */ +.highlight .dl { color: #aa5500 } /* Literal.String.Delimiter */ +.highlight .sd { color: #aa5500 } /* Literal.String.Doc */ +.highlight .s2 { color: #aa5500 } /* Literal.String.Double */ +.highlight .se { color: #aa5500 } /* Literal.String.Escape */ +.highlight .sh { color: #aa5500 } /* Literal.String.Heredoc */ +.highlight .si { color: #aa5500 } /* Literal.String.Interpol */ +.highlight .sx { color: #aa5500 } /* Literal.String.Other */ +.highlight .sr { color: #009999 } /* Literal.String.Regex */ +.highlight .s1 { color: #aa5500 } /* Literal.String.Single */ +.highlight .ss { color: #0000aa } /* Literal.String.Symbol */ +.highlight .bp { color: #00aaaa } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #00aa00 } /* Name.Function.Magic */ +.highlight .vc { color: #aa0000 } /* Name.Variable.Class */ +.highlight .vg { color: #aa0000 } /* Name.Variable.Global */ +.highlight .vi { color: #aa0000 } /* Name.Variable.Instance */ +.highlight .vm { color: #aa0000 } /* Name.Variable.Magic */ +.highlight .il { color: #009999 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/manual/v3.0.0/ja/_static/searchtools.js b/manual/v3.0.0/ja/_static/searchtools.js new file mode 100644 index 00000000..2c774d17 --- /dev/null +++ b/manual/v3.0.0/ja/_static/searchtools.js @@ -0,0 +1,632 @@ +/* + * Sphinx JavaScript utilities for the full-text search. + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + SearchResultKind.title, + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + SearchResultKind.text, + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/manual/v3.0.0/ja/_static/sphinx_highlight.js b/manual/v3.0.0/ja/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/manual/v3.0.0/ja/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/manual/v3.0.0/ja/_static/translations.js b/manual/v3.0.0/ja/_static/translations.js new file mode 100644 index 00000000..635b0818 --- /dev/null +++ b/manual/v3.0.0/ja/_static/translations.js @@ -0,0 +1,62 @@ +Documentation.addTranslations({ + "locale": "ja", + "messages": { + "%(filename)s — %(docstitle)s": "%(filename)s — %(docstitle)s", + "© %(copyright_prefix)s %(copyright)s.": "", + ", in ": ", in ", + "About these documents": "\u3053\u306e\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u306b\u3064\u3044\u3066", + "Automatically generated list of changes in version %(version)s": "\u30d0\u30fc\u30b8\u30e7\u30f3 %(version)s \u306e\u5909\u66f4\u70b9\uff08\u3053\u306e\u30ea\u30b9\u30c8\u306f\u81ea\u52d5\u751f\u6210\u3055\u308c\u3066\u3044\u307e\u3059\uff09", + "C API changes": "C API \u306b\u95a2\u3059\u308b\u5909\u66f4", + "Changes in Version %(version)s — %(docstitle)s": "\u30d0\u30fc\u30b8\u30e7\u30f3 %(version)s \u306e\u5909\u66f4\u70b9 — %(docstitle)s", + "Collapse sidebar": "\u30b5\u30a4\u30c9\u30d0\u30fc\u3092\u305f\u305f\u3080", + "Complete Table of Contents": "\u7dcf\u5408\u76ee\u6b21", + "Contents": "\u30b3\u30f3\u30c6\u30f3\u30c4", + "Copyright": "\u8457\u4f5c\u6a29", + "Created using Sphinx %(sphinx_version)s.": "", + "Expand sidebar": "\u30b5\u30a4\u30c9\u30d0\u30fc\u3092\u5c55\u958b", + "Full index on one page": "\u7dcf\u7d22\u5f15", + "General Index": "\u7dcf\u5408\u7d22\u5f15", + "Global Module Index": "\u30e2\u30b8\u30e5\u30fc\u30eb\u7dcf\u7d22\u5f15", + "Go": "\u691c\u7d22", + "Hide Search Matches": "\u691c\u7d22\u7d50\u679c\u3092\u96a0\u3059", + "Index": "\u7d22\u5f15", + "Index – %(key)s": "", + "Index pages by letter": "\u982d\u6587\u5b57\u5225\u7d22\u5f15", + "Indices and tables:": "\u7d22\u5f15\u3068\u8868\u4e00\u89a7:", + "Last updated on %(last_updated)s.": "\u6700\u7d42\u66f4\u65b0: %(last_updated)s", + "Library changes": "\u30e9\u30a4\u30d6\u30e9\u30ea\u306b\u95a2\u3059\u308b\u5909\u66f4", + "Navigation": "\u30ca\u30d3\u30b2\u30fc\u30b7\u30e7\u30f3", + "Next topic": "\u6b21\u306e\u30c8\u30d4\u30c3\u30af\u3078", + "Other changes": "\u305d\u306e\u4ed6\u306e\u5909\u66f4", + "Overview": "\u6982\u8981", + "Please activate JavaScript to enable the search\n functionality.": "\u691c\u7d22\u6a5f\u80fd\u3092\u4f7f\u3046\u306b\u306f JavaScript \u3092\u6709\u52b9\u306b\u3057\u3066\u304f\u3060\u3055\u3044\u3002", + "Preparing search...": "\u691c\u7d22\u3092\u6e96\u5099\u3057\u3066\u3044\u307e\u3059...", + "Previous topic": "\u524d\u306e\u30c8\u30d4\u30c3\u30af\u3078", + "Quick search": "\u30af\u30a4\u30c3\u30af\u691c\u7d22", + "Search": "\u691c\u7d22", + "Search Page": "\u691c\u7d22\u30da\u30fc\u30b8", + "Search Results": "\u691c\u7d22\u7d50\u679c", + "Search finished, found one page matching the search query.": [ + "" + ], + "Search within %(docstitle)s": "%(docstitle)s \u5185\u3092\u691c\u7d22", + "Searching": "\u691c\u7d22\u4e2d", + "Searching for multiple words only shows matches that contain\n all words.": "\u8907\u6570\u306e\u5358\u8a9e\u3092\u691c\u7d22\u3059\u308b\u3068\u3001\u6b21\u3092\u542b\u3080\u4e00\u81f4\u306e\u307f\u304c\u8868\u793a\u3055\u308c\u307e\u3059\n \u00a0\u00a0\u00a0 \u3059\u3079\u3066\u306e\u7528\u8a9e\u3002", + "Show Source": "\u30bd\u30fc\u30b9\u30b3\u30fc\u30c9\u3092\u8868\u793a", + "Table of Contents": "\u76ee\u6b21", + "This Page": "\u3053\u306e\u30da\u30fc\u30b8", + "Welcome! This is": "Welcome! This is", + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "\u691c\u7d22\u3057\u305f\u6587\u5b57\u5217\u306f\u3069\u306e\u6587\u66f8\u306b\u3082\u898b\u3064\u304b\u308a\u307e\u305b\u3093\u3067\u3057\u305f\u3002\u3059\u3079\u3066\u306e\u5358\u8a9e\u304c\u6b63\u78ba\u306b\u8a18\u8ff0\u3055\u308c\u3066\u3044\u308b\u304b\u3001\u3042\u308b\u3044\u306f\u3001\u5341\u5206\u306a\u30ab\u30c6\u30b4\u30ea\u30fc\u304c\u9078\u629e\u3055\u308c\u3066\u3044\u308b\u304b\u78ba\u8a8d\u3057\u3066\u304f\u3060\u3055\u3044\u3002", + "all functions, classes, terms": "\u95a2\u6570\u3001\u30af\u30e9\u30b9\u304a\u3088\u3073\u7528\u8a9e\u7dcf\u89a7", + "can be huge": "\u5927\u304d\u3044\u5834\u5408\u304c\u3042\u308b\u306e\u3067\u6ce8\u610f", + "last updated": "\u6700\u7d42\u66f4\u65b0", + "lists all sections and subsections": "\u7ae0\uff0f\u7bc0\u4e00\u89a7", + "next chapter": "\u6b21\u306e\u7ae0\u3078", + "previous chapter": "\u524d\u306e\u7ae0\u3078", + "quick access to all modules": "\u5168\u30e2\u30b8\u30e5\u30fc\u30eb\u65e9\u898b\u8868", + "search": "\u691c\u7d22", + "search this documentation": "\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u3092\u691c\u7d22", + "the documentation for": "the documentation for" + }, + "plural_expr": "0" +}); \ No newline at end of file diff --git a/manual/v3.0.0/ja/acknowledgement.html b/manual/v3.0.0/ja/acknowledgement.html new file mode 100644 index 00000000..f96cf0b7 --- /dev/null +++ b/manual/v3.0.0/ja/acknowledgement.html @@ -0,0 +1,64 @@ + + + + + + + + 謝辞 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

謝辞

+

本ソフトウェアの開発は、科研費 19H04125, 20H00581, 21K19773, 23K18465 および東京大学物性研究所 ソフトウェア開発・高度化プロジェクト (2020, 2021, 2024 年度) の支援を受け開発されました。

+

本ソフトウェアの設計・変数命名の一部は abics を参考にしています。 +また、ソルバーの追加方法について、塚本恭平氏(物性研)にチュートリアルを追加していただきました。この場を借りて感謝します。

+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/algorithm/bayes.html b/manual/v3.0.0/ja/algorithm/bayes.html new file mode 100644 index 00000000..7175e681 --- /dev/null +++ b/manual/v3.0.0/ja/algorithm/bayes.html @@ -0,0 +1,218 @@ + + + + + + + + ベイズ最適化 bayes — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

ベイズ最適化 bayes

+

bayes はベイズ最適化を用いてパラメータ探索を行う Algorithm です。 +実装には PHYSBO を用いています。

+
+

前準備

+

あらかじめ PHYSBO をインストールしておく必要があります。

+
$ python3 -m pip install physbo
+
+
+

mpi4py がインストールされている場合、MPI 並列計算が可能です。

+
+
+

入力パラメータ

+
+

[algorithmparam] セクション

+

探索パラメータ空間を定義します。

+

mesh_path が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。

+

mesh_path が定義されていない場合は、 min_list, max_list, num_list を用いて、 +各パラメータについて等間隔なグリッドを作成します。

+
    +

  • mesh_path

    +

    形式: string型

    +

    説明: メッシュデータの情報が記載された参照用ファイルへのパス。

    +
    • +

  • min_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最小値。

    +
    • +

  • max_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最大値。

    +
    • +

  • num_list

    +

    形式: 整数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる数。

    +
    • +
+
+
+

[algorithm.bayes] セクション

+

手法のハイパーパラメータを定義します。

+
    +

  • random_max_num_probes

    +

    形式： int型 (default: 20)

    +

    説明: ベイズ最適化を行う前に行うランダムサンプリングの回数(パラメータとスコアが初めに無い場合にはランダムサンプリングは必須)。

    +
    • +

  • bayes_max_num_probes

    +

    形式： int型 (default: 40)

    +

    説明: ベイズ最適化を行う回数。

    +
    • +

  • score

    +

    形式: string型 (default: TS )

    +

    説明: スコア関数を指定するパラメータ。 +EI, PI, TS より選択可能で、それぞれ "expected improvement", "probability of improvement", "Thompson sampling" を行います。

    +
    • +

  • interval

    +

    形式： int型 (default: 5)

    +

    説明: 指定したインターバルごとに、ハイパーパラメータを学習します。負の値を指定すると、ハイパーパラメータの学習は行われません。 +0を指定すると、ハイパーパラメータの学習は最初のステップでのみ行われます。

    +
    • +

  • num_rand_basis

    +

    形式： int型 (default: 5000)

    +

    説明： 基底関数の数。0を指定した場合、Bayesian linear modelを利用しない通常のガウシアンプロセスが行われます。

    +
    • +
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス、 +2列目以降は [solver.param] セクションにある、 +string_list で定義された変数に入る値が入ります。

+

以下、サンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

出力ファイル

+
+

BayesData.txt

+

最適化過程の各ステップにおいて、 +パラメータと対応する目的関数の値が、 +これまでの最適パラメータとそのステップで探索したパラメータの順に記載されます。

+
#step z1 z2 R-factor z1_action z2_action R-factor_action
+0 4.75 4.5 0.05141906746102885 4.75 4.5 0.05141906746102885
+1 4.75 4.5 0.05141906746102885 6.0 4.75 0.06591878368102033
+2 5.5 4.25 0.04380131351780189 5.5 4.25 0.04380131351780189
+3 5.0 4.25 0.02312528177606794 5.0 4.25 0.02312528177606794
+...
+
+
+
+
+
+

リスタート

+

コンストラクタの引数 run_mode に実行モードを指定します。 +以下はそれぞれ odatse コマンドの引数の --init, --resume, --cont に対応します。 +各モードの動作は次のとおりです。

+
    +

  • "initial" (デフォルト)

    +

    初期化して実行します。 +まず、ランダムサンプリングを random_max_num_probes に指定した回数だけ行います。 +次に、ベイズ最適化を bayes_max_num_probes に指定した回数実行します。

    +

    チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。

    +
      +

    1. ランダムサンプリングが終了したとき

      2. +

    2. ベイズ最適化の繰り返しの途中で、指定したステップ数または実行時間が経過したとき

      3. +

    3. 実行の終了時

      4. +
    +
    • +

  • "resume"

    +

    実行が中断した際に、最も新しいチェックポイントから実行を再開します。 +並列数などの計算条件は前と同じにする必要があります。

    +

    なお、並列実行の場合、実行を中断して resume した結果は、中断なしで実行した結果と完全には一致しません。

    +
    • +

  • "continue"

    +

    終了時の状態からベイズ最適化の繰り返しを継続して実行するモードです。 +bayes_max_num_probes の値を増やしてプログラムを実行してください。 +繰り返しステップカウントはそのまま引き継がれます。

    +

    例: 前の計算で bayes_max_num_probes = 100 として 100ステップ計算した後、次の計算で bayes_max_num_probes = 200 として continue モードで実行すると、101ステップ目から 200ステップ目までの計算を行います。

    +
    • +
+
+
+

アルゴリズム解説

+

ベイズ最適化 (Bayesian optimization, BO) は、機械学習を援用した最適化アルゴリズムであり、特に目的関数の評価に時間がかかるときに強力な手法です。

+

BO では目的関数 \(f(\vec{x})\) を、評価が早く最適化のしやすいモデル関数(多くの場合ガウス過程) \(g(\vec{x})\) で近似します。 +\(g\) は、あらかじめ適当に決められたいくつかの点(訓練データセット) \(\{\vec{x}_i\}_{i=1}^N\) での目的関数の値 \(\{f(\vec{x}_i)\}_{i=1}^N\) をよく再現するように訓練されます。 +パラメータ空間の各点において、訓練された \(g(\vec{x})\) の値の期待値およびその誤差から求められる「スコア」 (acquition function) が最適になるような点 \(\vec{x}_{N+1}\) を次の計算候補点として提案します。 +\(f(\vec{x}_{N+1})\) を評価し、 訓練データセットに追加、 \(g\) を再訓練します。 +こうした探索を適当な回数繰り返した後、目的関数の値が最も良かったものを最適解として返します。

+

少ない誤差でより良い期待値を与える点は、正解である可能性こそ高いですが、すでに十分な情報があると考えられるので、モデル関数の精度向上にはあまり寄与しません。 +逆に、誤差の大きな点は正解ではないかもしれませんが、情報の少ない場所であり、モデル関数の更新には有益だと考えられます。 +前者を選ぶことを「活用」、後者を選ぶことを「探索」とよび、両者をバランス良く行うのが重要です。 +「スコア」の定義はこれらをどう選ぶかを定めます。

+

ODAT-SE では、ベイズ最適化のライブラリとして、 PHYSBO を用います。 +PHYSBO は mapper_mpi のように、あらかじめ決めておいた候補点の集合に対して「スコア」を計算して、最適解を提案します。 +候補点の集合を分割することでMPI 並列実行が可能です。 +また、 訓練データの点数 \(N\) に対して線形の計算量でモデル関数の評価、ひいては「スコア」の計算が可能となるようなカーネルを用いています。 +PHYSBO では「スコア」関数として "expected improvement (EI)", "probability of improvement (PI)", "Thompson sampling (TS)" が利用できます。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/algorithm/exchange.html b/manual/v3.0.0/ja/algorithm/exchange.html new file mode 100644 index 00000000..a19fa487 --- /dev/null +++ b/manual/v3.0.0/ja/algorithm/exchange.html @@ -0,0 +1,354 @@ + + + + + + + + 交換モンテカルロ法 exchange — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

交換モンテカルロ法 exchange

+

exchange はレプリカ交換モンテカルロ法を用いてパラメータ探索を行う Algorithm です。

+
+

前準備

+

MPI並列を利用する場合は、あらかじめ mpi4py をインストールしておきます。

+
$ python3 -m pip install mpi4py
+
+
+
+
+

入力パラメータ

+

サブセクション param と exchange を持ちます。

+
+

[param] セクション

+

探索空間を定義します。 +mesh_path キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。

+
    +

  • 連続空間

    +
      +

    • initial_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +

      説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。

      +
      • +

    • min_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最小値。

      モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +

    • max_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最大値。

      モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +

    • step_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +

      説明: モンテカルロ更新の際の変化幅(ガウス分布の偏差)です。

      +
      • +
    +
    • +

  • 離散空間

    +
      +

    • mesh_path

      +

      形式: ファイルパス

      +

      説明: メッシュ定義ファイル。

      +
      • +

    • neighborlist_path

      +

      形式: ファイルパス

      +

      説明: 近傍リスト定義ファイル。

      +
      • +
    +
    • +
+
+
+

[exchange] セクション

+
    +

  • numsteps

    +

    形式: 整数値。

    +

    説明: モンテカルロ更新を行う回数。

    +
    • +

  • numsteps_exchange

    +

    形式: 整数値。

    +

    説明: 「温度」のレプリカ交換を行う頻度。この回数だけモンテカルロ更新を行ったらレプリカ交換を実行します。

    +
    • +

  • Tmin

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最小値。

    +
    • +

  • Tmax

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最大値。

    +
    • +

  • bmin

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最小値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • bmax

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最大値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • Tlogspace

    +

    形式: 真偽値。 (default: true)

    +
    +
    説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。

    true のときは対数空間で等分割します。

    +
    +
    +
    • +

  • nreplica_per_proc

    +

    形式: 整数。 (default: 1)

    +

    説明: ひとつのMPI プロセスが担当するレプリカの数。

    +
    • +
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス (実際には使用されません)、 +2列目以降は探索空間の座標を指定します。

+

以下、サンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

近傍リスト定義ファイル

+

離散空間をモンテカルロ法で探索する場合、各点 \(i\) ごとに次に移動できる点 \(j\) を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。

+

1列目に始点の番号 \(i\) を記載し、 +2列目以降に \(i\) から移動できる終点 \(j\) を列挙します。

+

近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール odatse_neighborlist が提供されています。 +詳細は 関連ツール を参照してください。

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

出力ファイル

+
+

RANK/trial.txt

+

各レプリカについて、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの温度、4列目に目的関数の値、5列目以降にパラメータが記載されます。

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.0758494287185766 2.811346329442423 3.691101784194861
+2 0 0.004999999999999999 0.08566823949124412 3.606664760390988 3.2093903670436497
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

RANK/result.txt

+

各レプリカについて、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +trial.txt と同一の書式です。

+
# step walker T fx z1 z2
+0 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+1 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+2 0 0.004999999999999999 0.07830821484593968 3.682008067401509 3.9502750191292586
+3 0 0.004999999999999999 0.06273922648753057 4.330900869594549 4.311333132184154
+
+
+
+
+

best_result.txt

+

サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

result_T#.txt

+

サンプリング結果を温度ごとにまとめ直したものです。 +# は温度点の番号です。 +ファイルの1 列目はステップ数、2列目は全体での walker 番号、3列目は目的関数の値、 4列目以降は探索パラメータの値です。

+
# T = 1.0
+0 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+1 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+2 15 28.70157662892569 3.3139009347685118 -4.20946994566609
+3 15 28.98676409223712 3.7442621319489637 -3.868754990884034
+
+
+
+
+
+

リスタート

+

コンストラクタの引数 run_mode に実行モードを指定します。 +以下はそれぞれ odatse コマンドの引数の --init, --resume, --cont に対応します。 +各モードの動作は次のとおりです。

+
    +

  • "initial" (デフォルト)

    +

    初期化して実行します。 +チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。

    +
      +

    1. 指定したステップ数または実行時間が経過したとき

      2. +

    2. 実行の終了時

      3. +
    +
    • +

  • "resume"

    +

    実行が中断した際に、最も新しいチェックポイントから実行を再開します。 +並列数などの計算条件は前と同じにする必要があります。

    +
    • +

  • "continue"

    +

    終了時の状態からサンプリングの繰り返しを継続して実行するモードです。 +numsteps の値を増やしてプログラムを実行してください。 +繰り返しステップカウントはそのまま引き継がれます。

    +

    例: 前の計算で numsteps = 1000 として 1000ステップ計算した後、次の計算で numsteps = 2000 として continue モードで実行すると、1001ステップ目から 2000ステップ目までの計算を行います。

    +
    • +
+
+
+

アルゴリズム解説

+
+

マルコフ連鎖モンテカルロ法

+

モンテカルロ法(モンテカルロサンプリング)では、パラメータ空間中を動き回る walker \(\vec{x}\) を重み \(W(\vec{x})\) に従って確率的に動かすことで目的関数の最適化を行います。 +重み \(W(\vec{x})\) として、「温度」 \(T > 0\) を導入して \(W(\vec{x}) = e^{-f(\vec{x})/T}\) とすることが一般的です(ボルツマン重み)。 +ほとんどの場合において、 \(W\) に基づいて直接サンプリングする (walker を生成する) のは不可能なので、 walker を確率的に少しずつ動かすことで、頻度分布が \(W\) に従うように時系列 \(\{\vec{x}_t\}\) を生成します (マルコフ連鎖モンテカルロ法, MCMC)。 +\(\vec{x}\) から \(\vec{x}'\) へ遷移する確率を \(p(\vec{x}' | \vec{x})\) とすると、

+
+\[W(\vec{x}') = \sum_{\vec{x}} p(\vec{x}' | \vec{x}) W(\vec{x})\]
+

となるように \(p\) を定めれば(釣り合い条件)、時系列 \(\{\vec{x}_t\}\) の頻度分布が \(W(\vec{x})\) に収束することが示されます。 [1] +実際の計算では、より強い制約である詳細釣り合い条件

+
+\[p(\vec{x} | \vec{x}') W(\vec{x}') = W(\vec{x})p(\vec{x}' | \vec{x})\]
+

を課すことがほとんどです。 両辺で \(\vec{x}\) についての和を取ると釣り合い条件に帰着します。

+

\(p\) を求めるアルゴリズムはいくつか提案されていますが、 ODAT-SE では Metropolis-Hasting 法 (MH法) を用います。 +MH 法では、遷移プロセスを提案プロセスと採択プロセスとに分割します。

+
    +

  1. 提案確率 \(P(\vec{x} | \vec{x}_t)\) で候補点 \(\vec{x}\) を生成します

    +

    提案確率 \(P\) としては \(\vec{x}_t\) を中心とした一様分布やガウス関数などの扱いやすいものを利用します

    +
    2. +

  2. 提案された候補点 \(\vec{x}\) を採択確率 \(Q(\vec{x}, | \vec{x}_t)\) で受け入れ、 \(\vec{x}_{t+1} = \vec{x}\) とします

    +

    受け入れなかった場合は \(\vec{x}_{t+1} = \vec{x}_t\) とします

    +
    3. +
+

採択確率 \(Q(\vec{x} | \vec{x}_t)\) は

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})P(\vec{x}_t | \vec{x}) }{W(\vec{x}_t) P(\vec{x} | \vec{x}_t)} \right]\]
+

とします。 +この定義が詳細釣り合い条件を満たすことは、詳細釣り合いの式に代入することで簡単に確かめられます。 +特に、重みとしてボルツマン因子を、提案確率として対称なもの \(P(\vec{x} | \vec{x}_t) = P(\vec{x}_t | \vec{x})\) を用いたときには、

+
+\[Q(\vec{x} | \vec{x}_t) = \min\left[1, \frac{W(\vec{x})}{W(\vec{x}_t)} \right] + = \min\left[1, \exp\left(-\frac{f(\vec{x}) - f(\vec{x}_t)}{T}\right) \right]\]
+

という更に簡単な形になります。

+

\(\Delta f = f(\vec{x}) - f(\vec{x}_t)\) とおいて、 +\(\Delta f \le 0\) のときに \(Q = 1\) となることを踏まえると、 +MH 法によるMCMC は次のようになります。

+
    +

  1. 現在地点の近くからランダムに次の座標の候補を選び、目的関数 \(f\) の値を調べる

    2. +

  2. \(\Delta f \le 0\) ならば(山を下る方向ならば)移動する

    3. +

  3. \(\Delta f > 0\) ならば採択確率 \(Q = e^{-\Delta f / T}\) で移動する

    4. +

  4. 1-3 を適当な回数繰り返す

    5. +
+

得られた時系列のうち、目的関数の値が一番小さいものを最適解とします。 +3 番のプロセスのおかげで、 \(\Delta f \sim T\) ぐらいの山を乗り越えられるので、局所最適解にトラップされた場合にも脱出可能です。

+
+
+

レプリカ交換モンテカルロ法

+

モンテカルロ法による最適化では、温度 \(T\) は非常に重要なハイパーパラメータとなっています。 +モンテカルロ法では、温度 \(T\) 程度の山を乗り越えられますが、逆にそれ以上の深さの谷からは容易に脱出できません。 +そのため、局所解へのトラップを防ぐためには温度を上げる必要があります。 +一方で、 \(T\) よりも小さい谷は谷として見えなくなるため、得られる \(\min f(\vec{x})\) の精度も \(T\) 程度になり、精度を上げるためには温度を下げる必要があります。 +ここから、最適解を探すためには温度 \(T\) を注意深く決める必要があることがわかります。

+

この問題を解決する方法として、温度 \(T\) を固定せずに更新していくというものがあります。 +たとえば、焼きなまし法 (simulated annealing) では、温度をステップごとに徐々に下げていきます。 +焼戻し法 (simulated tempering) は、温度をハイパーパラメータではなく、サンプリングすべきパラメータとして扱い、(詳細)釣り合い条件を満たすように更新することで、加熱と冷却を実現します。温度を下げることで谷の詳細を調べ、温度を上げることで谷から脱出します。 +レプリカ交換モンテカルロ法 (replica exchange Monte Carlo) は焼戻し法を更に発展させた手法で、並列焼戻し法 (parallel tempering) とも呼ばれます。 +レプリカ交換モンテカルロ法では、レプリカと呼ばれる複数の系を、それぞれ異なる温度で並列にモンテカルロシミュレーションします。 +そして、ある一定間隔で、(詳細)釣り合い条件を満たすように他のレプリカと温度を交換します。 +焼戻し法と同様に、温度を上下することで谷を調べたり脱出したりするのですが、各温度点について、かならずレプリカのどれかが対応しているため、全体として特定の温度に偏ることがなくなります。 +また、複数の MPI プロセスを用意してそれぞれレプリカを担当させることで簡単に並列化可能です。 +数多くのレプリカを用意することで温度間隔が狭まると、温度交換の採択率も上がるため、大規模並列計算に特に向いたアルゴリズムです。 +有限温度由来の「ぼやけ」がどうしても生まれるので、モンテカルロ法の結果を初期値として minsearch をするのがおすすめです。

+

脚注

+ +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/algorithm/index.html b/manual/v3.0.0/ja/algorithm/index.html new file mode 100644 index 00000000..854ac421 --- /dev/null +++ b/manual/v3.0.0/ja/algorithm/index.html @@ -0,0 +1,73 @@ + + + + + + + + 探索アルゴリズム — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

探索アルゴリズム

+

探索アルゴリズム Algorithm は Solver の結果 \(f(x)\) を用いて +パラメータ空間 \(\mathbf{X} \ni x\) を探索し、 \(f(x)\) の最小化問題を解きます。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/algorithm/mapper_mpi.html b/manual/v3.0.0/ja/algorithm/mapper_mpi.html new file mode 100644 index 00000000..01dc0b9e --- /dev/null +++ b/manual/v3.0.0/ja/algorithm/mapper_mpi.html @@ -0,0 +1,170 @@ + + + + + + + + グリッド型探索 mapper — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

グリッド型探索 mapper

+

mapper_mpi はパラメータ空間中の候補点をあらかじめ用意しておいて、そのすべてで \(f(x)\) を計算することで最小値を探索するアルゴリズムです。 +MPI 実行した場合、候補点の集合を等分割して各プロセスに自動的に割り振ることで自明並列計算を行います。

+
+

前準備

+

MPI 並列を行う場合は、 mpi4py をインストールしておく必要があります。

+
$ python3 -m pip install mpi4py
+
+
+
+
+

入力パラメータ

+
+

[param] セクション

+

探索パラメータ空間を定義します。

+

mesh_path が定義されている場合はメッシュファイルから読み込みます。 +メッシュファイルは1行がパラメータ空間中の1点を意味しており、 +1列目がデータ番号で、2列目以降が各次元の座標です。

+

mesh_path が定義されていない場合は、 min_list, max_list, num_list を用いて、 +各パラメータについて等間隔なグリッドを作成します。

+
    +

  • mesh_path

    +

    形式: string型

    +

    説明: メッシュ定義ファイルへのパス。

    +
    • +

  • min_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最小値。

    +
    • +

  • max_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる最大値。

    +
    • +

  • num_list

    +

    形式: 整数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータが取りうる数。

    +
    • +
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1 + dimension 列のテキストファイルで、 +1列目にメッシュのインデックス、 +2列目以降は探索パラメータ \(x\) に対応する値を記載します。 +また、 # から始まる行はコメントとして無視されます。

+

以下、2次元パラメータ空間探索のサンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+
+

出力ファイル

+
+

ColorMap.txt

+

各メッシュでの候補パラメータと、その点での目的関数の値が記載されたファイルです。 +メッシュデータは、入力ファイルの [solver.param] セクションにある string_list で定義された変数の順番で記載され、最後に目的関数の値が記載されます。

+

以下、出力例です。

+
6.000000 6.000000 0.047852
+6.000000 5.750000 0.055011
+6.000000 5.500000 0.053190
+6.000000 5.250000 0.038905
+6.000000 5.000000 0.047674
+6.000000 4.750000 0.065919
+6.000000 4.500000 0.053675
+6.000000 4.250000 0.061261
+6.000000 4.000000 0.069351
+6.000000 3.750000 0.071868
+...
+
+
+
+
+
+

リスタート

+

コンストラクタの引数 run_mode に実行モードを指定します。 +以下はそれぞれ odatse コマンドの引数の --init, --resume, --cont に対応します。 +各モードの動作は次のとおりです。

+
    +

  • "initial" (デフォルト)

    +

    初期化して実行します。 +チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。

    +
      +

    1. 指定した数のグリッド点を評価したとき、または指定した実行時間が経過したとき

      2. +

    2. 実行の終了時

      3. +
    +
    • +

  • "resume"

    +

    実行が中断した際に、最も新しいチェックポイントから実行を再開します。 +並列数などの計算条件は前と同じにする必要があります。

    +
    • +

  • "continue"

    +

    continue には対応していません。

    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/algorithm/minsearch.html b/manual/v3.0.0/ja/algorithm/minsearch.html new file mode 100644 index 00000000..a30af4da --- /dev/null +++ b/manual/v3.0.0/ja/algorithm/minsearch.html @@ -0,0 +1,177 @@ + + + + + + + + Nelder-Mead 法 minsearch — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

Nelder-Mead 法 minsearch

+

minsearch は Nelder-Mead 法 (a.k.a. downhill simplex 法) によって最適化を行います。 +Nelder-Mead 法では、 パラメータ空間の次元を \(D\) として、 \(D+1\) 個の座標点の組を、各点での目的関数の値に応じて系統的に動かすことで最適解を探索します。

+

重要なハイパーパラメータとして、座標の初期値があります。 +局所最適解にトラップされるという問題があるので、初期値を変えた計算を何回か繰り返して結果を確認することをおすすめします。

+

ODAT-SEは、SciPy の scipy.optimize.minimize(method="Nelder-Mead") 関数を用いています。 +詳しくは 公式ドキュメント をご参照ください。

+
+

前準備

+

あらかじめ scipy をインストールしておく必要があります。

+
python3 -m pip install scipy
+
+
+
+
+

入力パラメータ

+

サブセクション param と minimize を持ちます。

+
+

[param] セクション

+
    +

  • initial_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。

    +
    • +

  • unit_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +
    +
    説明: 各パラメータの単位。

    探索アルゴリズム中では、各パラメータをそれぞれこれらの値で割ることで、 +簡易的な無次元化・正規化を行います。 +定義しなかった場合にはすべての次元で 1.0 となります。

    +
    +
    +
    • +

  • min_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +
    +
    説明: パラメータが取りうる最小値。

    最適化中にこの値を下回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

    +
    +
    +
    • +

  • max_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +
    +
    説明: パラメータが取りうる最大値。

    最適化中にこの値を上回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

    +
    +
    +
    • +
+
+
+

[minimize] セクション

+

Nelder-Mead 法のハイパーパラメータを設定します。 +詳細は scipy.optimize.minimize のドキュメントを参照してください。

+
    +

  • initial_scale_list

    +

    形式: 実数型のリスト。長さはdimensionの値と一致させます。

    +

    説明: Nelder-Mead 法の初期 simplex を作るために、初期値からずらす差分。 +initial_list と、 initial_list に initial_scale_list の成分ひとつを足してできるdimension 個の点を 合わせたものが initial_simplex として使われます。 +定義しなかった場合、各次元に 0.25 が設定されます。

    +
    • +

  • xatol

    +

    形式: 実数型 (default: 1e-4)

    +

    説明: Nelder-Mead 法の収束判定に使うパラメータ

    +
    • +

  • fatol

    +

    形式: 実数型 (default: 1e-4)

    +

    説明: Nelder-Mead 法の収束判定に使うパラメータ

    +
    • +

  • maxiter

    +

    形式: 整数 (default: 10000)

    +

    説明: Nelder-Mead 法の反復回数の最大値

    +
    • +

  • maxfev

    +

    形式: 整数 (default: 100000)

    +

    説明: 目的関数を評価する回数の最大値

    +
    • +
+
+
+
+

出力ファイル

+
+

SimplexData.txt

+

最小値を求める途中経過に関する情報を出力します。 +1行目はヘッダー、2行目以降にstep、入力ファイルの [solver.param] セクションにある +string_list で定義された変数の値、最後に関数の値が出力されます。

+

以下、出力例です。

+
#step z1 z2 z3 R-factor
+0 5.25 4.25 3.5 0.015199251773721183
+1 5.25 4.25 3.5 0.015199251773721183
+2 5.229166666666666 4.3125 3.645833333333333 0.013702918021532375
+3 5.225694444444445 4.40625 3.5451388888888884 0.012635279378225261
+4 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+5 5.179976851851851 4.348958333333334 3.5943287037037033 0.006001660077530159
+
+
+
+
+

res.txt

+

最終的に得られた目的関数の値とその時のパラメータの値を記載しています。 +最初に目的関数、その後は入力ファイルの [solver.param] セクションにある string_list で定義された変数の値が順に記載されます。

+

以下、出力例です。

+
fx = 7.382680568652868e-06
+z1 = 5.230524973874179
+z2 = 4.370622919269477
+z3 = 3.5961444501081647
+
+
+
+
+
+

リスタート

+

Nelder-Mead法による最適値探索はリスタートに対応していません。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/algorithm/pamc.html b/manual/v3.0.0/ja/algorithm/pamc.html new file mode 100644 index 00000000..bb74219b --- /dev/null +++ b/manual/v3.0.0/ja/algorithm/pamc.html @@ -0,0 +1,461 @@ + + + + + + + + ポピュレーションアニーリングモンテカルロ法 pamc — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

ポピュレーションアニーリングモンテカルロ法 pamc

+

pamc はポピュレーションアニーリングモンテカルロ法を用いてパラメータ探索を行う Algorithm です。

+
+

前準備

+

MPI 並列をする場合にはあらかじめ mpi4py をインストールしておく必要があります。

+
$ python3 -m pip install mpi4py
+
+
+
+
+

入力パラメータ

+

サブセクション param と pamc を持ちます。

+
+

[param] セクション

+

探索空間を定義します。 +mesh_path キーが存在する場合は離散空間を、そうでない場合は連続空間を探索します。

+
    +

  • 連続空間

    +
      +

    • initial_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +

      説明: パラメータの初期値。 定義しなかった場合は一様ランダムに初期化されます。

      +
      • +

    • min_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最小値。

      モンテカルロ探索中にこの値を下回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +

    • max_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +
      +
      説明: パラメータが取りうる最大値。

      モンテカルロ探索中にこの値を上回るパラメータが出現した場合、 +ソルバーは評価されずに、値が無限大だとみなされます。

      +
      +
      +
      • +

    • step_list

      +

      形式: 実数型のリスト。長さはdimensionの値と一致させます。

      +

      説明: モンテカルロ更新の際の変化幅(ガウス分布の偏差)です。

      +
      • +
    +
    • +

  • 離散空間

    +
      +

    • mesh_path

      +

      形式: ファイルパス

      +

      説明: メッシュ定義ファイル。

      +
      • +

    • neighborlist_path

      +

      形式: ファイルパス

      +

      説明: 近傍リスト定義ファイル。

      +
      • +
    +
    • +
+
+
+

[pamc] セクション

+
    +

  • numsteps

    +

    形式: 整数値。

    +

    説明: モンテカルロ更新を行う総回数。

    +
    • +

  • numsteps_annealing

    +

    形式: 整数値。

    +

    説明: 「温度」を下げる頻度。この回数モンテカルロ更新を行った後に温度が下がります。

    +
    • +

  • Tnum

    +

    形式: 整数値。

    +

    説明: 「温度」点の数。

    +
    • +

  • Tmin

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最小値。

    +
    • +

  • Tmax

    +

    形式: 実数値。

    +

    説明: 「温度」(\(T\))の最大値。

    +
    • +

  • bmin

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最小値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • bmax

    +

    形式: 実数値。

    +

    説明: 「逆温度」(\(\beta = 1/T\))の最大値。 +温度と逆温度はどちらか片方だけを指定する必要があります。

    +
    • +

  • Tlogspace

    +

    形式: 真偽値。 (default: true)

    +
    +
    説明: 「温度」を各レプリカに割り当てる際に、対数空間で等分割するか否かを指定します。

    true のときは対数空間で等分割します。

    +
    +
    +
    • +

  • nreplica_per_proc

    +

    形式: 整数。 (default: 1)

    +

    説明: ひとつのMPI プロセスが担当するレプリカの数。

    +
    • +

  • resampling_interval

    +

    形式: 整数。 (default: 1)

    +

    説明: レプリカのリサンプリングを行う頻度。この回数だけ温度降下を行った後にリサンプリングが行われます。

    +
    • +

  • fix_num_replicas

    +

    形式: 真偽値。 (default: true)

    +

    説明: リサンプリングの際、レプリカ数を固定するかどうか。

    +
    • +
+
+

ステップ数について

+

numsteps, numsteps_annealing, numT の3つのうち、どれか2つを同時に指定してください。 +残りの1つは自動的に決定されます。

+
+
+
+
+

アルゴリズム補助ファイル

+
+

メッシュ定義ファイル

+

本ファイルで探索するグリッド空間を定義します。 +1列目にメッシュのインデックス(実際には使用されません)、 +2列目以降は探索空間の座標を指定します。

+

以下、サンプルを記載します。

+
1 6.000000 6.000000
+2 6.000000 5.750000
+3 6.000000 5.500000
+4 6.000000 5.250000
+5 6.000000 5.000000
+6 6.000000 4.750000
+7 6.000000 4.500000
+8 6.000000 4.250000
+9 6.000000 4.000000
+...
+
+
+
+
+

近傍リスト定義ファイル

+

離散空間をモンテカルロ法で探索する場合、各点 \(i\) ごとに次に移動できる点 \(j\) を定めておく必要があります。 +そのために必要なのが近傍リスト定義ファイルです。

+

1列目に始点の番号 \(i\) を記載し、 +2列目以降に \(i\) から移動できる終点 \(j\) を列挙します。

+

近傍リスト定義ファイルをメッシュ定義ファイルから生成するツール odatse_neighborlist が提供されています。 +詳細は 関連ツール を参照してください。

+
0 1 2 3
+1 0 2 3 4
+2 0 1 3 4 5
+3 0 1 2 4 5 6 7
+4 1 2 3 5 6 7 8
+5 2 3 4 7 8 9
+...
+
+
+
+
+
+

出力ファイル

+
+

RANK/trial_T#.txt

+

各温度点(#) ごと、モンテカルロサンプリングで提案されたパラメータと、対応する目的関数の値です。 +1列目にステップ数、2列目にプロセス内のwalker 番号、3列目にレプリカの逆温度、4列目に目的関数の値、5列目からパラメータが記載されます。 +最後の2列はそれぞれレプリカの重み (Neal-Jarzynski weight) と祖先(計算開始時のレプリカ番号)です。

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/trial.txt

+

trial_T#.txt をすべてまとめたものです。

+
+
+

RANK/result_T#.txt

+

各温度点、モンテカルロサンプリングで生成されたパラメータと、対応する目的関数の値です。 +trial.txt と同一の書式です。

+
# step walker beta fx x1 weight ancestor
+0 0 0.0 73.82799488298886 8.592321856342956 1.0 0
+0 1 0.0 13.487174782058675 -3.672488908364282 1.0 1
+0 2 0.0 39.96292704464803 -6.321623766458111 1.0 2
+0 3 0.0 34.913851603463 -5.908794428939206 1.0 3
+0 4 0.0 1.834671825646121 1.354500581633733 1.0 4
+0 5 0.0 3.65151610695736 1.910894059585031 1.0 5
+...
+
+
+
+
+

RANK/result.txt

+

result_T#.txt をすべてまとめたものです。

+
+
+

best_result.txt

+

サンプリングされた全データのうち、目的関数の値が最小となったパラメータと、対応する目的関数の値です。

+
nprocs = 4
+rank = 2
+step = 65
+fx = 0.008233957976993406
+z1 = 4.221129370933539
+z2 = 5.139591716517661
+
+
+
+
+

fx.txt

+

各温度ごとに、全レプリカの情報をまとめたものです。 +1列目は逆温度が、2列目と3列目には目的関数の期待値およびその標準誤差が、4列目にはレプリカの総数が、5列目には規格化因子(分配関数)の比の対数

+
+\[\log\frac{Z}{Z_0} = \log\int \mathrm{d}x e^{-\beta f(x)} - \log\int \mathrm{d}x e^{-\beta_0 f(x)}\]
+

が、6列目にはモンテカルロ更新の採択率が出力されます。 +ここで \(\beta_0\) は計算している \(\beta\) の最小値です。

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.0 33.36426034198166 3.0193077565358273 100 0.0 0.9804
+0.1 4.518006242920819 0.9535301415484388 100 -1.2134775491597027 0.9058
+0.2 1.5919146358616842 0.2770369776964151 100 -1.538611313376179 0.9004
+...
+
+
+
+
+
+

リスタート

+

コンストラクタの引数 run_mode に実行モードを指定します。 +以下はそれぞれ odatse コマンドの引数の --init, --resume, --cont に対応します。 +各モードの動作は次のとおりです。

+
    +

  • "initial" (デフォルト)

    +

    初期化して実行します。 +チェックポイント機能が有効な場合、以下のタイミングで実行時の状態をファイルに出力します。

    +
      +

    1. 各温度点の計算が終わった時点で、指定したステップ数または実行時間が経過したとき

      2. +

    2. 実行の終了時

      3. +
    +
    • +

  • "resume"

    +

    実行が中断した際に、最も新しいチェックポイントから実行を再開します。 +並列数などの計算条件は前と同じにする必要があります。

    +
    • +

  • "continue"

    +

    実行終了後の状態から継続して実行します。 +温度点のリストを、前の計算から連続するように指定する必要があります。

    +

    前の計算で Tmax= \(T^{(1)}\) から Tmin= \(T^{(2)}\) に下げた場合、 +次の計算では Tmax= \(T^{(2)}\), Tmin= \(T^{(3)}\) のように指定します。 +新たな計算では、 \(T^{(2)}\) から \(T^{(3)}\) までを Tnum に分割した温度点の列 +\(T_0 = T^{(2)}\), \(T_1\),..., \(T_{\text{Tnum}-1}=T^{(3)}\) +について計算を行います。(Tnum は前の計算から変更して構いません。)

    +
    • +
+
+
+

アルゴリズム解説

+
+

問題と目的

+

分布パラメータ \(\beta_i\) のもとでの配位 \(x\) の重みを +\(f_i(x)\) と書くと(例えばボルツマン因子 \(f_i(x) = \exp\left[-\beta_i E(x)\right]\))、 +\(A\) の期待値は

+
+\[\langle A\rangle_i += \frac{\int \mathrm{d}xA(x)f_i(x)}{\int \mathrm{d}x f_i(x)} += \frac{1}{Z}\int \mathrm{d}xA(x)f_i(x) += \int \mathrm{d}xA(x)\tilde{f}_i(x)\]
+

とかけます。 +ここで \(Z = \int \mathrm{d} x f_i(x)\) は規格化因子(分配関数)で、 \(\tilde{f}(x) = f(x)/Z\) は配位 \(x\) の確率密度です。

+

目的は複数の分布パラメータについてこの期待値および規格化因子(の比)を数値的に求めることです。

+
+
+

Annealed Importance Sampling (AIS) [1]

+

次の同時確率分布

+
+\[\tilde{f}(x_0, x_1, \dots, x_n) = \tilde{f}_n(x_n) \tilde{T}_n(x_n, x_{n-1}) \tilde{T}_{n-1}(x_{n-1}, x_{n-2}) \cdots \tilde{T}_1(x_1, x_0)\]
+

を満たす点列 \(\{x_i\}\) を考えます。ここで

+
+\[\tilde{T}_i(x_i, x_{i-1}) = T_i(x_{i-1}, x_i) \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)}\]
+

であり、 \(T_i(x, x')\) は \(\beta_i\) のもとでの配位 \(x\) +から \(x'\) への遷移確率で、釣り合い条件

+
+\[\int \mathrm{d}x \tilde{f}_i(x) T_i(x, x') = \tilde{f}_i(x')\]
+

を満たすようにとります(つまりは普通のMCMCにおける遷移確率行列)。

+
+\[\int \mathrm{d} x_{i-1} \tilde{T}_i(x_i, x_{i-1}) += \int \mathrm{d} x_{i-1} \tilde{f}_i(x_{i-1}) T_i(x_{i-1}, x_i) / \tilde{f}_i(x_i) += 1\]
+

となるので、 \(\tilde{f}_n(x_n)\) は +\(\tilde{f}(x_0, x_1, \dots, x_n)\) の周辺分布

+
+\[\tilde{f}_n(x_n) = \int \prod_{i=0}^{n-1} \mathrm{d} x_i \tilde{f}(x_0, x_1, \dots, x_n)\]
+

です。 +これを利用すると、 \(\tilde{f}_n\) における平均値 \(\langle A \rangle_n\) は拡張した配位の重み付き平均として

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&\equiv +\int \mathrm{d} x_n A(x_n) \tilde{f}_n(x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) +\end{split}\end{split}\]
+

と表せます。

+

さて、残念ながら \(\tilde{f}(x_0, x_1, \dots, x_n)\) +に従うような点列を直接生成することは困難です。そこでもっと簡単に、

+
    +

  1. 確率 \(\tilde{f}_0(x)\) に従う \(x_0\) を生成する

    +
      +

    • 例えば MCMC を利用する

      • +
    +
    2. +

  2. \(x_i\) から \(T_{i+1}(x_i, x_{i+1})\) によって \(x_{i+1}\) を生成する

    +
      +

    • \(T_{i+1}\) は釣り合い条件を満たすような遷移確率行列なので、普通にMCMCを行えば良い

      • +
    +
    3. +
+

という流れに従って点列 \(\{x_i\}\) を生成すると、これは同時確率分布

+
+\[\tilde{g}(x_0, x_1, \dots, x_n) = \tilde{f}_0(x_0) T_1(x_0, x_1) T_2(x_1, x_2) \dots T_n(x_{n-1}, x_n)\]
+

に従います。これを利用すると期待値 \(\langle A \rangle_n\) は

+
+\[\begin{split}\begin{split} +\langle A \rangle_n +&= \int \prod_i \mathrm{d} x_i A(x_n) \tilde{f}(x_0, x_1, \dots, x_n) \\ +&= \int \prod_i \mathrm{d} x_i A(x_n) \frac{\tilde{f}(x_0, x_1, \dots, x_n)}{\tilde{g}(x_0, x_1, \dots, x_n)} \tilde{g}(x_0, x_1, \dots, x_n) \\ +&= \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} +\end{split}\end{split}\]
+

と評価できます (reweighting method)。 +\(\tilde{f}\) と \(\tilde{g}\) との比は、

+
+\[\begin{split}\begin{split} +\frac{\tilde{f}(x_0, \dots, x_n)}{\tilde{g}(x_0, \dots, x_n)} +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{T}_i(x_i, x_{i-1})}{T(x_{i-1}, x_i)} \\ +&= +\frac{\tilde{f}_n(x_n)}{\tilde{f}_0(x_0)} +\prod_{i=1}^n \frac{\tilde{f}_i(x_{i-1})}{\tilde{f}_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\frac{f_n(x_n)}{f_0(x_0)} +\prod_{i=1}^n \frac{f_i(x_{i-1})}{f_i(x_i)} \\ +&= +\frac{Z_0}{Z_n} +\prod_{i=0}^{n-1} \frac{f_{i+1}(x_{i})}{f_i(x_i)} \\ +&\equiv +\frac{Z_0}{Z_n} w_n(x_0, x_1, \dots, x_n) +\end{split}\end{split}\]
+

とかけるので、期待値は

+
+\[\langle A \rangle_n = \left\langle A\tilde{f}\big/\tilde{g} \right\rangle_{g, n} += \frac{Z_0}{Z_n} \langle Aw_n \rangle_{g,n}\]
+

となります。 +規格化因子の比 \(Z_n/Z_0\) は \(\langle 1 \rangle_n = 1\) を用いると

+
+\[\frac{Z_n}{Z_0} = \langle w_n \rangle_{g,n}\]
+

と評価できるので、 \(A\) の期待値は

+
+\[\langle A \rangle_n = \frac{\langle Aw_n \rangle_{g,n}}{\langle w_n \rangle_{g,n}}\]
+

という、重み付き平均の形で評価できます。 +この重み \(w_n\) を Neal-Jarzynski 重みと呼びます。

+
+
+

population annealing (PA) [2]

+

AIS を使うと各 \(\beta\) に対する期待値を重み付き平均という形で計算できますが、 +\(\beta\) の幅が大きくなると重み \(w\) の分散が大きくなってしまいます。 +そのため、適当な周期で確率 \(p^{(k)} = w^{(k)} / \sum_k w^{(k)}\) に従いレプリカをリサンプリングし、 +レプリカに割当られた重みをリセット \((w=1)\) します。

+

PAMC のアルゴリズムは次の擬似コードで示されます:

+
for k in range(K):
+    w[0, k] = 1.0
+    x[0, k] = draw_from(β[0])
+for i in range(1, N):
+    for k in range(K):
+        w[i, k] = w[i-1, k] * ( f(x[i-1,k], β[i]) / f(x[i-1,k], β[i-1]) )
+    if i % interval == 0:
+        x[i, :] = resample(x[i, :], w[i, :])
+        w[i, :] = 1.0
+    for k in range(K):
+        x[i, k] = transfer(x[i-1, k], β[i])
+    a[i] = sum(A(x[i,:]) * w[i,:]) / sum(w[i,:])
+
+
+

リサンプリング手法として、レプリカ数を固定する方法[2]と固定しない方法[3]の2通りがあります。

+
+
+

参考文献

+

[1] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[2] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[3] J. Machta, PRE 82, 026704 (2010).

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/contact.html b/manual/v3.0.0/ja/contact.html new file mode 100644 index 00000000..0a107fc6 --- /dev/null +++ b/manual/v3.0.0/ja/contact.html @@ -0,0 +1,74 @@ + + + + + + + + お問い合わせ — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + +
+ + +
+

お問い合わせ

+

ODAT-SE に関するお問い合わせはこちらにお寄せください。

+
    +

  • バグ報告

    +

    ODAT-SE のバグ関連の報告は GitHubのIssues で受け付けています。

    +

    バグを早期に解決するため、報告時には次のガイドラインに従ってください。

    +
    +
      +

    • 使用している ODAT-SE のバージョンを指定してください。

      • +

    • インストールに問題がある場合には、使用しているオペレーティングシステムとコンパイラの情報についてお知らせください。

      • +

    • 実行に問題が生じた場合は、実行に使用した入力ファイルとその出力を記載してください。

      • +
    +
    +
    • +

  • その他

    +

    研究に関連するトピックなどGitHubのIssuesで相談しづらいことを問い合わせる際には、以下の連絡先にコンタクトをしてください。

    +

    E-mail: 2dmat-dev__at__issp.u-tokyo.ac.jp (_at_を@に変更してください)

    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/customize/algorithm.html b/manual/v3.0.0/ja/customize/algorithm.html new file mode 100644 index 00000000..21c8b371 --- /dev/null +++ b/manual/v3.0.0/ja/customize/algorithm.html @@ -0,0 +1,297 @@ + + + + + + + + Algorithm の定義 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

Algorithm の定義

+

Algorithm クラスは odatse.algorithm.AlgorithmBase を継承したクラスとして定義します。

+
import odatse
+
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    pass
+
+
+
+

AlgorithmBase

+

AlgorithmBase クラスは次のメソッドを提供します。

+
    +

  • __init__(self, info: odatse.Info, runner: odatse.Runner = None)

    +
    +
      +

    • info から Algorithm 共通の入力パラメータを読み取り、次のインスタンス変数を設定します。

      +
      +
        +

      • self.mpicomm: Optional[MPI.Comm] : MPI.COMM_WORLD

        +
        +
          +

        • mpi4py の import に失敗した場合、 None が設定されます

          • +
        +
        +
        • +

      • self.mpisize: int : MPIプロセス数

        +
        +
          +

        • mpi4py の import に失敗した場合、 1 が設定されます

          • +
        +
        +
        • +

      • self.mpirank: int : MPIランク

        +
        +
          +

        • mpi4py の import に失敗した場合、 0 が設定されます

          • +
        +
        +
        • +

      • self.rng: np.random.Generator : 擬似乱数生成器

        +
        +
        +
        +
        • +

      • self.dimension: int : 探索パラメータ空間の次元

        • +

      • self.label_list: List[str] : 各パラメータの名前

        • +

      • self.root_dir: pathlib.Path : ルートディレクトリ

        +
        +
          +

        • info.base["root_dir"]

          • +
        +
        +
        • +

      • self.output_dir: pathlib.Path : 出力ファイルを書き出すディレクトリ

        +
        +
          +

        • info.base["root_dir"]

          • +
        +
        +
        • +

      • self.proc_dir: pathlib.Path : プロセスごとの作業用ディレクトリ

        +
        +
          +

        • self.output_dir / str(self.mpirank)

          • +

        • ディレクトリが存在しない場合、自動的に作成されます

          • +

        • 各プロセスで最適化アルゴリズムはこのディレクトリで実行されます

          • +
        +
        +
        • +

      • self.timer: Dict[str, Dict] : 実行時間を保存するための辞書

        +
        +
          +

        • 空の辞書が3つ、 "prepare", "run", "post" という名前で定義されます

          • +
        +
        +
        • +

      • self.checkpoint : チェックポイント機能を有効/無効にする

        +
        +
          +

        • self.checkpoint_steps

          • +

        • self.checkpoint_interval

          • +

        • self.checkpoint_file

          +

          チェックポイント機能に関するパラメータが設定されます

          +
          • +
        +
        +
        • +
      +
      +
      • +
    +
    +
    • +

  • prepare(self) -> None

    +
    +
      +

    • 最適化アルゴリズムの前処理をします

      • +

    • self.run() の前に実行する必要があります

      • +
    +
    +
    • +

  • run(self) -> None

    +
    +
      +

    • 最適化アルゴリズムを実行します

      • +

    • 以下の処理を行います

      +
        +

      1. self.proc_dir に移動する

        2. +

      2. self.runner.prepare() を実行する

        3. +

      3. self._run() を実行する

        4. +

      4. self.runner.post() を実行する

        5. +

      5. 元のディレクトリに戻る

        6. +
      +
      • +

    • self.prepare() の後に実行する必要があります

      • +
    +
    +
    • +

  • post(self) -> Dict

    +
    +
      +

    • 最適化結果のファイル出力など、後処理を行います

      • +

    • self.output_dir に移動し、 self._post() を実行した後、元のディレクトリに戻ります

      • +

    • self.run() のあとに実行する必要があります

      • +
    +
    +
    • +

  • main(self, run_mode) -> Dict

    +
    +
      +

    • prepare, run, post を順番に実行します

      • +

    • それぞれの関数でかかった時間を計測し、結果をファイル出力します

      • +

    • 実行モードを文字列型の引数で受け取ります。デフォルト値は initialize です。

      +
        +

      • "initialize": 最初から実行

        • +

      • "resume": 中断した状態から再実行

        • +

      • "continue": 終了時の状態から継続実行

        • +
      +

      乱数の初期化を指示する場合は、 "-resetrand" が追加されます。 +"continue" の動作はアルゴリズムによって変わります。

      +
      • +

    • 探索の結果を辞書形式で返します

      • +
    +
    +
    • +
+
+
+

Algorithm

+

Algorithm は少なくとも次のメソッドを定義しなければなりません。

+
    +

  • __init__(self, info: odatse.Info, runner: odatse.Runner = None, domain = None)

    +
    +
      +

    • info および runner 引数はそのまま基底クラスのコンストラクタに転送してください

      +
      +
        +

      • super().__init__(info=info, runner=runner)

        • +
      +
      +
      • +

    • 入力パラメータである info から必要な設定を読み取り、保存してください

      • +

    • domain が指定されている場合は、探索領域を domain から取得します。 +指定されていない場合は odatse.domain.Region(info) (探索領域が連続的な場合) または odatse.domain.MeshGrid(info) (離散的な場合) を用いて info から作成します。

      • +
    +
    +
    • +

  • _prepare(self) -> None

    +
    +
      +

    • 最適化アルゴリズムの前処理を記述します

      • +
    +
    +
    • +

  • _run(self) -> None

    +
    +
      +

    • 最適化アルゴリズムを記述します

      • +

    • 探索パラメータ x から対応する目的関数の値 f(x) を得るには、次のように Runner クラスのメソッドを呼び出します。

      +
      args = (step, set)
+fx = self.runner.submit(x, args)
+
      +
      +
      • +
    +
    +
    • +

  • _post(self) -> Dict

    +
    +
      +

    • 最適化アルゴリズムの後処理を記述します

      • +

    • 探索の結果を辞書形式で返します

      • +
    +
    +
    • +
+
+
+

Domain の定義

+

探索領域を記述する 2種類のクラスが用意されています。

+
+

Region クラス

+

連続的なパラメータ空間を定義するためのヘルパークラスです。

+
    +

  • コンストラクタ引数は Info または param= にdict形式のパラメータを取ります。

    +
      +

    • Info 型の引数の場合、 Info.algorithm.param から探索範囲の最小値・最大値・単位や初期値を取得します。

      • +

    • dict 型の引数の場合は Info.algorithm.param 相当の内容を辞書形式で受け取ります。

      • +

    • 詳細は min_search の入力ファイル を参照してください。

      • +
    +
    • +

  • initialize(self, rng, limitation, num_walkers) を呼んで初期値の設定を行います。引数は乱数発生器 rng, 制約条件 limitation, walker の数 num_walkers です。

    • +
+
+
+

MeshGrid クラス

+

離散的的なパラメータ空間を定義するためのヘルパークラスです。

+
    +

  • コンストラクタ引数は Info または param= にdict形式のパラメータを取ります。

    +
      +

    • Info 型の引数の場合、 Info.algorithm.param から探索範囲の最小値・最大値・単位や初期値を取得します。

      • +

    • dict 型の引数の場合は Info.algorithm.param 相当の内容を辞書形式で受け取ります。

      • +

    • 詳細は mapper の入力ファイル を参照してください

      • +
    +
    • +

  • do_split(self) メソッドは、候補点の集合を分割して各MPIランクに配分します。

    • +

  • 入出力について

    +
      +

    • from_file(cls, path) クラスメソッドは、 path からメッシュデータを読み込んで MeshGrid クラスのインスタンスを作成します。

      • +

    • store_file(self, path) メソッドは、メッシュの情報を path のファイルに書き出します。

      • +
    +
    • +
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/customize/common.html b/manual/v3.0.0/ja/customize/common.html new file mode 100644 index 00000000..7efdee03 --- /dev/null +++ b/manual/v3.0.0/ja/customize/common.html @@ -0,0 +1,175 @@ + + + + + + + + 共通事項 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

共通事項

+

Solver と Algorithm に共通する事柄について説明します。

+
+

odatse.Info

+

入力パラメータを扱うためのクラスです。 +インスタンス変数として次の4つの dict を持ちます。

+
    +

  • base

    +
    +
      +

    • ディレクトリ情報など、プログラム全体で共通するパラメータ

      • +
    +
    +
    • +

  • solver

    +
    +
      +

    • Solver が用いる入力パラメータ

      • +
    +
    +
    • +

  • algorithm

    +
    +
      +

    • Algorithm が用いる入力パラメータ

      • +
    +
    +
    • +

  • runner

    +
    +
      +

    • Runner が用いる入力パラメータ

      • +
    +
    +
    • +
+

Info は base, solver, algorithm, runner の4つのキー(省略可)を持つ dict を渡して初期化できます。また、クラスメソッド from_file に TOML形式の入力ファイルへのパスを渡して作成することもできます。

+
+

base について

+

要素として計算のルートディレクトリ root_dir と出力のルートディレクトリ output_dir が自動で設定されます

+
    +

  • ルートディレクトリ root_dir

    +
      +

    • デフォルトはカレントディレクトリ "." です

      • +

    • 絶対パスに変換されたものがあらためて root_dir に設定されます

      • +

    • 先頭の ~ はホームディレクトリに展開されます

      • +

    • 具体的には次のコードが実行されます

      +
      p = pathlib.Path(base.get("root_dir", "."))
+base["root_dir"] = p.expanduser().absolute()
+
      +
      +
      • +
    +
    • +

  • 出力ディレクトリ output_dir

    +
      +

    • 先頭の ~ はホームディレクトリに展開されます

      • +

    • 絶対パスが設定されていた場合はそのまま設定されます

      • +

    • 相対パスが設定されていた場合、 root_dir を起点とした相対パスとして解釈されます

      • +

    • デフォルトは "." 、つまり root_dir と同一ディレクトリです

      • +

    • 具体的には次のコードが実行されます

      +
      p = pathlib.Path(base.get("work_dir", "."))
+p = p.expanduser()
+base["work_dir"] = base["root_dir"] / p
+
      +
      +
      • +
    +
    • +
+
+
+
+

odatse.Runner

+

Runner は Algorithm と Solver とをつなげるためのクラスです。 +コンストラクタ引数として Solver のインスタンス、 Info のインスタンス、パラメータの変換を記述する Mapping のインスタンス、制約条件を記述する Limitation のインスタンスを取ります。 +Mapping のインスタンスを省略した場合は変換しない TrivialMapping が仮定されます。 +Limitation のインスタンスを省略した場合は、制約を課さない Unlimited が仮定されます。

+

submit(self, x: np.ndarray, args: Tuple[int,int]) -> float メソッドは、探索パラメータ x とオプションパラメータ args に対してソルバーを実行し、結果として目的関数の値 f(x) を返します。 +関数を評価する際に Limitation のインスタンスを用いて探索パラメータ x が制約を満たしているかを確認します。次に Mapping のインスタンスを用いて x から実際にソルバーが使う入力 y = mapping(x) を得ます。

+

その他、 Runner で使われる info の詳細は 入力ファイル を参照してください。

+
+
+

odatse.Mapping

+

Mapping は逆問題解析アルゴリズムの探索パラメータから順問題ソルバーの変数へのマッピングを記述するクラスです。 __call__(self, x: np.ndarray) -> np.ndarray メソッドを持つ関数オブジェクトとして定義します。 +現在は自明な変換 TrivialMapping とアフィン写像 Affine のクラスが定義されています。

+
+

TrivialMapping

+

自明なマッピング \(x\to x\) (変換しない)を与えるクラスです。 +Runner クラスの引数のデフォルト値となります。

+
+
+

Affine

+

アフィン変換 \(x \to y=Ax+b\) を与えるクラスです。 +要素 A, b はコンストラクタの引数に指定するか、 from_dict クラスメソッドに辞書の形式で与えます。 +ODAT-SEの入力ファイルに指定する場合、パラメータの指定方法は「入力ファイル」の mapping セクションを参照してください。

+
+
+
+

odatse.Limitation

+

Limitation は逆問題解析アルゴリズムで探索する \(N\) 次元のパラメータ \(x\) に課す制約条件を与えるクラスです。 judge(self, x: np.ndarray) -> bool のメソッドを持つクラスとして定義します。 +現在は制約なし Unlimited と線形不等式制約 Inequality のクラスが定義されています。

+
+

Unlimited

+

制約条件を課さないというクラスです。 judge メソッドは常に True を返します。 +Runner クラスの引数のデフォルト値となります。

+
+
+

Inequality

+

\(N\) 次元の探索パラメータ \(x\) に対して、 \(M\) 行 \(N\) 列の行列 \(A\) と \(M\) 次元のベクトル \(b\) で与えられる \(M\) 個の制約条件 \(A x + b > 0\) を課すクラスです。

+

要素 A, b はコンストラクタの引数に指定するか、 from_dict クラスメソッドに辞書の形式で与えます。 +ODAT-SEの入力ファイルに指定する場合、パラメータの指定方法は「入力ファイル」の limitation セクションを参照してください。

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/customize/index.html b/manual/v3.0.0/ja/customize/index.html new file mode 100644 index 00000000..53e5b28d --- /dev/null +++ b/manual/v3.0.0/ja/customize/index.html @@ -0,0 +1,73 @@ + + + + + + + + (開発者向け)ユーザー定義アルゴリズム・ソルバー — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

(開発者向け)ユーザー定義アルゴリズム・ソルバー

+

本ソフトウェアは、順問題のためのソルバー Solver と最適化のためのアルゴリズム Algorithm を組み合わせることで全体の逆問題を解きます。 +Solver と Algorithm はすでに定義済みのものがいくつかありますが、これらを自分で定義することで、適用範囲を広げられます。 +本章では、 Solver や Algorithm を定義する方法およびこれらを使用する方法を解説します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/customize/solver.html b/manual/v3.0.0/ja/customize/solver.html new file mode 100644 index 00000000..6e871c5f --- /dev/null +++ b/manual/v3.0.0/ja/customize/solver.html @@ -0,0 +1,111 @@ + + + + + + + + Solver の定義 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

Solver の定義

+

順問題を記述する Solver は、入力変数に対して目的関数の値を返す evaluate メソッドを持つクラスとして以下のように定義します。

+
    +

  • Solver クラスは odatse.solver.SolverBase を継承するクラスとします。

    +
    import odatse
+
+class Solver(odatse.solver.SolverBase):
+    pass
+
    +
    +
    • +

  • コンストラクタ

    +

    コンストラクタは Info クラスのメソッドを引数としてとります。

    +
    def __init__(self, info: odatse.Info):
+    super().__init__(info)
+    ...
+
    +
    +

    必ず info を引数として基底クラスのコンストラクタを呼び出してください。 +基底クラスのコンストラクタでは、次のインスタンス変数が設定されます。

    +
      +

    • self.root_dir はルートディレクトリです。 info.base["root_dir"] から取得され、 odatse を実行するディレクトリになります。外部プログラムやデータファイルなどを参照する際に起点として利用できます。

      • +

    • self.output_dir は出力ファイルを書き出すディレクトリです。 info.base["output_dir"] から取得されます。通例、MPI並列の場合は各ランクからのデータを集約した結果を出力します。

      • +

    • self.proc_dir はプロセスごとの作業用ディレクトリです。 output_dir / str(self.mpirank) が設定されます。 +ソルバーの evaluate メソッドは proc_dir をカレントディレクトリとして Runner から呼び出され、MPIプロセスごとの中間結果などを出力します。 +MPIを使用しない場合もランク番号を0として扱います。

      • +
    +

    Solver 固有のパラメータは info の solver フィールドから取得します。必要な設定を読み取って保存します。

    +
    • +

  • evaluate メソッド

    +
    def evaluate(self, x, args=(), nprocs=1, nthreads=1) -> float:
+    pass
+
    +
    +

    入力変数に対して目的変数の値を返すメソッドです。以下の引数を取ります。

    +
      +

    • x: np.ndarray

      +

      入力変数を numpy.ndarray 型の \(N\) 次元ベクトルとして受け取ります。

      +
      • +

    • args: Tuple = ()

      +

      Algorithm から渡される追加の引数で、step数と set番号からなる Tuple です。step数は Monte Carlo のステップ数や、グリッド探索のグリッド点のインデックスです。set番号は n巡目を表します。

      +
      • +

    • nprocs: int = 1

      • +

    • nthreads: int = 1

      +

      ソルバーを MPI並列・スレッド並列で実行する際のプロセス数・スレッド数を受け取ります。現在は procs=1, nthreads=1 のみ対応しています。

      +
      • +
    +

    evaluate メソッドは、Float 型の目的関数の値を返します。

    +
    • +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/customize/usage.html b/manual/v3.0.0/ja/customize/usage.html new file mode 100644 index 00000000..cf623b74 --- /dev/null +++ b/manual/v3.0.0/ja/customize/usage.html @@ -0,0 +1,103 @@ + + + + + + + + 実行方法 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

実行方法

+

次のようなフローで最適化問題を実行できます。 +プログラム例にあるコメントの番号はフローの番号に対応しています。

+
    +

  1. ユーザ定義クラスを作成する

    +
      +

    • ODAT-SEで定義済みのクラスも利用可能です

      • +
    +
    2. +

  2. 入力パラメータ info: odatse.Info を作成する

    +
      +

    • Info クラスにはTOML形式の入力ファイルを読み込むクラスメソッドが用意されています。この他にも、dict形式でパラメータを用意して Info クラスのコンストラクタに渡して作成することができます。

      • +
    +
    3. +

  3. solver: Solver, runner: odatse.Runner, algorithm: Algorithm を作成する

    4. +

  4. algorithm.main() を実行する

    5. +
+

プログラム例

+
import sys
+import odatse
+
+# (1)
+class Solver(odatse.solver.SolverBase):
+    # Define your solver
+    pass
+
+class Algorithm(odatse.algorithm.AlgorithmBase):
+    # Define your algorithm
+    pass
+
+# (2)
+input_file = sys.argv[1]
+info = odatse.Info.from_file(input_file)
+
+# (3)
+solver = Solver(info)
+runner = odatse.Runner(solver, info)
+algorithm = Algorithm(info, runner)
+
+# (4)
+result = algorithm.main()
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/genindex.html b/manual/v3.0.0/ja/genindex.html new file mode 100644 index 00000000..0898e551 --- /dev/null +++ b/manual/v3.0.0/ja/genindex.html @@ -0,0 +1,53 @@ + + + + + + + 索引 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + +
+ + + +

索引

+ +
+ +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/index.html b/manual/v3.0.0/ja/index.html new file mode 100644 index 00000000..1a6da276 --- /dev/null +++ b/manual/v3.0.0/ja/index.html @@ -0,0 +1,123 @@ + + + + + + + + Welcome to ODAT-SE documentation! — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

Welcome to ODAT-SE documentation!

+
+

Contents:

+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/input.html b/manual/v3.0.0/ja/input.html new file mode 100644 index 00000000..8147a64b --- /dev/null +++ b/manual/v3.0.0/ja/input.html @@ -0,0 +1,329 @@ + + + + + + + + 入力ファイル — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

入力ファイル

+

ODAT-SE は入力ファイルの形式に TOML を採用しています。 +入力ファイルは次の4つのセクションから構成されます。

+
    +

  • base

    +
      +

    • ODAT-SE 全体のパラメータを指定します。

      • +
    +
    • +

  • solver

    +
      +

    • Solver のパラメータを指定します。

      • +
    +
    • +

  • algorithm

    +
      +

    • Algorithm のパラメータを指定します。

      • +
    +
    • +

  • runner

    +
      +

    • Runner のパラメータを指定します。

      • +
    +
    • +
+
+

[base] セクション

+
    +

  • dimension

    +

    形式: 整数型

    +

    説明: 探索空間の次元(探索するパラメータの数)

    +
    • +

  • root_dir

    +

    形式: string型 (default: プログラム実行時のディレクトリ)

    +
    +
    説明: プログラムを実行する一番上のディレクトリ。

    入力ファイルなどのパスはすべて root_dir を起点とします。

    +
    +
    +
    • +

  • output_dir

    +

    形式: string型 (default: プログラム実行時のディレクトリ)

    +

    説明: プログラムの実行結果を出力するディレクトリ名

    +
    • +
+
+
+

[solver] セクション

+

name でソルバーの種類を決定します。各パラメータはソルバーごとに定義されています。

+
    +

  • name

    +

    形式: string型

    +

    説明: ソルバーの名前。以下のソルバーが用意されています。

    +
    +
      +

    • analytical : 解析関数を与えるソルバー (主にテストに利用)

      • +
    +

    以下は別モジュールとして配布される2次元物質構造解析向けソルバーです。

    +
      +

    • sim-trhepd-rheed : 反射高速(陽)電子回折(RHEED, TRHEPD)の強度計算をするためのソルバー

      • +

    • sxrd : 表面X線回折(SXRD)解析のためのソルバー

      • +

    • leed : 低速電子線回折(LEED)解析のためのソルバー

      • +
    +
    +
    • +

  • dimension

    +

    形式: 整数型 (default: base.dimension)

    +

    説明: ソルバーが受け取る入力パラメータの数。

    +
    • +
+

各種ソルバーの詳細および入出力ファイルは 順問題ソルバー を参照してください。

+
+
+

[algorithm] セクション

+

name でアルゴリズムの種類を決定します。各パラメータはアルゴリズムごとに定義されています。

+
    +

  • name

    +

    形式: string型

    +

    説明: アルゴリズムの名前。以下のアルゴリズムが用意されています。

    +
    +
      +

    • minsearch: Nelder-Mead法による最小値探索

      • +

    • mapper: グリッド探索

      • +

    • exchange: レプリカ交換モンテカルロ法

      • +

    • pamc: ポピュレーションアニーリングモンテカルロ法

      • +

    • bayes: ベイズ最適化

      • +
    +
    +
    • +

  • seed

    +

    形式: 整数値

    +
    +
    説明: 初期値のランダム生成やモンテカルロ更新などで用いる擬似乱数生成器の種を指定します。

    各MPIプロセスに対して、 seed + mpi_rank * seed_delta の値が実際の種として用いられます。 +省略した場合は Numpy の規定の方法 で初期化されます。

    +
    +
    +
    • +

  • seed_delta

    +

    形式: 整数値 (default: 314159)

    +
    +
    説明: 疑似乱数生成器の種について、MPI プロセスごとの値を計算する際に用いられます。

    詳しくは seed を参照してください。

    +
    +
    +
    • +

  • checkpoint

    +

    形式: bool値 (default: false)

    +

    説明: 実行中および終了時の状態を定期的にファイルに出力します。実行が中断した場合に、チェックポイントから実行を再開できます。

    +
    • +

  • checkpoint_steps

    +

    形式: 整数値 (default: 16,777,216)

    +

    説明: 次のチェックポイントまでの繰り返し回数を指定します。繰り返し回数は、mapper の場合はグリッド点の数、bayes の場合は探索点の評価回数、モンテカルロ法(exchange, pamc) の場合は local update の回数です。 +デフォルト値は十分大きな数が設定されています。チェックポイント機能を有効にするには、 checkpoint_steps または checkpoint_interval の少なくとも一方を設定する必要があります。

    +
    • +

  • checkpoint_interval

    +

    形式: 実数値 (default: 31,104,000)

    +

    説明: 次のチェックポイントまでの経過時間を指定します。単位は秒です。 +デフォルト値は十分大きな数(360日)が設定されています。チェックポイント機能を有効にするには、 checkpoint_steps または checkpoint_interval の少なくとも一方を設定する必要があります。

    +
    • +

  • checkpoint_file

    +

    形式: 文字列 (default: "status.pickle")

    +

    説明: 実行中の状態を書き出すファイル名を指定します。ファイルはプロセスごとの出力ディレクトリに書き出されます。過去3世代分のファイルが .1, .2, .3 の suffix を付けて保存されます。

    +
    • +
+

各種アルゴリズムの詳細および入出力ファイルは 探索アルゴリズム を参照してください。

+
+
+

[runner] セクション

+

Algorithm と Solver を橋渡しする要素である Runner の設定を記述します。 +サブセクションとして mapping, limitation, log を持ちます。

+
+

[runner.mapping] セクション

+

Algorithm で探索している \(N\) 次元のパラメータ \(x\) から Solver で使う \(M\) 次元のパラメータ \(y\) への写像を定義します。 +\(N \ne M\) となる場合には、 solver セクションにも dimension パラメータを指定してください。

+

現在はアフィン写像(線形写像+平行移動) \(y = Ax+b\) が利用可能です。

+
    +

  • A

    +

    形式: リストのリスト、あるいは文字列 (default: [])

    +
    +
    説明: \(N \times M\) の変換行列 \(A\) 。空のリストを渡した場合、単位行列とみなされます。

    文字列として与える場合はそのまま行列の要素を空白および改行で区切って並べてください。

    +
    +
    +
    • +

  • b

    +

    形式: リスト、あるいは文字列 (default: [])

    +
    +
    説明: \(M\) 次元の並進移動ベクトル \(b\) 。空のリストを渡した場合、ゼロベクトルとみなされます。

    文字列として与える場合はそのままベクトルの要素を空白区切りで並べてください。

    +
    +
    +
    • +
+

行列の指定方法について、例えば、

+
A = [[1,1], [0,1]]
+
+
+

と

+
A = """
+1 1
+0 1
+"""
+
+
+

はともに

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right)\end{split}\]
+

を表します。

+
+
+

[runner.limitation] セクション

+

Algorithm で探索している \(N\) 次元のパラメータ \(x\) に、制約条件を課すことが出来ます。 +Algorithm ごとに定義する探索範囲(例：exchange の min_list や max_list ) に加えて課すことが出来ます。 +現在は \(M\) 行 \(N\) 列の行列 \(A\) と \(M\) 次元の縦ベクトル \(b\) から定義される \(Ax+b>0\) の制約式が利用可能です。具体的に

+
+\[\begin{split}A_{1,1} x_{1} + A_{1,2} x_{2} + &... + A_{1,N} x_{N} + b_{1} > 0\\ +A_{2,1} x_{1} + A_{2,2} x_{2} + &... + A_{2,N} x_{N} + b_{2} > 0\\ +&...\\ +A_{M,1} x_{1} + A_{M,2} x_{2} + &... + A_{M,N} x_{N} + b_{M} > 0\end{split}\]
+

という制約をかけることができます。 +ここで \(M\) は制約式の個数(任意)となります。

+
    +

  • co_a

    +

    形式: リストのリスト、あるいは文字列 (default: [])

    +

    説明: 制約式の行列 \(A\) を設定します。

    +
    +

    行数は制約式数 \(M\) 、列数は探索変数の数 \(N\) である必要があります。

    +

    co_b を同時に定義する必要があります。

    +
    +
    • +

  • co_b

    +

    形式: リストのリスト、あるいは文字列 (default: [])

    +

    説明: 制約式の縦ベクトル \(b\) を設定します。

    +
    +

    次元数が制約式数 \(M\) の縦ベクトルを設定する必要があります。

    +

    co_a を同時に定義する必要があります。

    +
    +
    • +
+

行列の指定方法について、[mapping] セクションと同様で、例えば、

+
A = [[1,1], [0,1]]
+
+
+

と

+
A = """
+1 1
+0 1
+"""
+
+
+

はともに

+
+\[\begin{split}A = \left( +\begin{matrix} +1 & 1 \\ +0 & 1 +\end{matrix} +\right)\end{split}\]
+

を表します。また、

+
co_b = [[0], [-1]]
+
+
+

と

+
co_b = """0 -1"""
+
+
+

と

+
co_b = """
+0
+-1
+"""
+
+
+

はともに

+
+\[\begin{split}b = \left( +\begin{matrix} +0 \\ +-1 +\end{matrix} +\right)\end{split}\]
+

を表します。 +co_a と co_b のどちらも定義しない場合、制約式を課さずに探索します。

+
+
+

[runner.log] セクション

+

solver 呼び出しのlogging に関する設定です。

+
    +

  • filename

    +

    形式: 文字列 (default: "runner.log")

    +

    説明: ログファイルの名前。

    +
    • +

  • interval

    +

    形式: 整数 (default: 0)

    +

    説明: solver を interval 回呼ぶ毎にログが書き出されます。0以下の場合、ログ書き出しは行われません。

    +
    • +

  • write_result

    +

    形式: 真偽値 (default: false)

    +

    説明: solver からの出力を記録するかどうかを指定します。

    +
    • +

  • write_input

    +

    形式: 真偽値 (default: false)

    +

    説明: solver への入力を記録するかどうかを指定します。

    +
    • +
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/introduction.html b/manual/v3.0.0/ja/introduction.html new file mode 100644 index 00000000..d0651367 --- /dev/null +++ b/manual/v3.0.0/ja/introduction.html @@ -0,0 +1,156 @@ + + + + + + + + はじめに — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

はじめに

+
+

ODAT-SEとは

+

Open Data Analysis Tool for Science and Engineering (ODAT-SE)は、順問題ソルバーに対して探索アルゴリズムを適用して最適解を探すためのフレームワークです。Version 2までは2DMATという名称で開発されてきましたが、Version 3からは順問題ソルバーと探索アルゴリズムをモジュール化した汎用のデータ解析プラットフォームとして整備しています。

+

順問題ソルバーはユーザー自身で定義することが可能です。 +標準的な順問題ソルバーとしては2次元物質構造解析向け実験データ解析ソフトウェアが用意されています。 +順問題ソルバーでは原子位置などをパラメータとし得られたデータと実験データとのずれを損失関数として与えます。 +探索アルゴリズムを組み合わせ、この損失関数を最小化することで、最適なパラメータを推定します。 +現バージョンでは、順問題ソルバーとして量子ビーム回折実験の全反射高速陽電子回折法(Total-reflection high-energy positron diffraction: TRHEPD)[1, 2], 表面X線回折法(sxrd)[3], 低速電子線回折法(leed)[4]に対応しており、探索アルゴリズムはNelder-Mead法[5], グリッド型探索法[6], ベイズ最適化[7], レプリカ交換モンテカルロ法[8], ポピュレーションアニーリングモンテカルロ法[9, 10, 11]が実装されています。

+

今後は、本フレームワークをもとにより多くの順問題ソルバーおよび探索アルゴリズムを実装していく予定です。

+

[1] レビューとして， Y．Fukaya, et al., J. Phys. D: Appl. Phys. 52, 013002 (2019); +兵頭俊夫，「全反射高速陽電子回折　(TRHEPD)による表面構造解析」，固体物理 53, 705 (2018).

+

[2] T. Hanada, Y. Motoyama, K. Yoshimi, and T. Hoshi, Computer Physics Communications 277, 108371 (2022).

+

[3] W. Voegeli, K. Akimoto, T. Aoyama, K. Sumitani, S. Nakatani, H. Tajiri, T. Takahashi, Y. Hisada, S. Mukainakano, X. Zhang, H. Sugiyama, H. Kawata, Applied Surface Science 252, 5259 (2006).

+

[4] M.A. Van Hove, W. Moritz, H. Over, P.J. Rous, A. Wander, A. Barbieri, N. Materer, U. Starke, G.A. Somorjai, Automated determination of complex surface structures by LEED, Surface Science Reports, Volume 19, 191-229 (1993).

+

[5] K. Tanaka, T. Hoshi, I. Mochizuki, T. Hanada, A. Ichimiya, and T. Hyodo, Acta. Phys. Pol. A 137, 188 (2020)..

+

[6] K. Tanaka, I. Mochizuki, T. Hanada, A. Ichimiya, T. Hyodo, and T. Hoshi, JJAP Conf. Series, 9, 011301 (2023)..

+

[7] Y. Motoyama, R. Tamura, K. Yoshimi, K. Terayama, T. Ueno, and K. Tsuda, Computer Physics Communications 278, 108405 (2022).

+

[8] K. Hukushima and K. Nemoto, J. Phys. Soc. Japan, 65, 1604 (1996)., R. Swendsen and J. Wang, Phys. Rev. Lett. 57, 2607 (1986).

+

[9] R. M. Neal, Statistics and Computing 11, 125-139 (2001).

+

[10] K. Hukushima and Y. Iba, AIP Conf. Proc. 690, 200 (2003).

+

[11] J. Machta, Phys. Rev. E 82, 026704 (2010).

+
+
+

ライセンス

+
+
本ソフトウェアのプログラムパッケージおよびソースコード一式は +Mozilla Public License version 2.0 (MPL-2.0) に準じて配布されています。
+
+

Copyright (c) <2020-> The University of Tokyo. All rights reserved.

+

本ソフトウェアは2020年度・2021年度・2024年度 東京大学物性研究所 ソフトウェア高度化プロジェクトの支援を受け開発されました。 +2DMAT / ODAT-SEを引用する際には以下の文献を引用してください。

+

"Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures", Y. Motoyama, K. Yoshimi, I. Mochizuki, H. Iwamoto, H. Ichinose, and T. Hoshi, Computer Physics Communications 280, 108465 (2022).

+

BibTeX:

+
@article{MOTOYAMA2022108465,
+  title = {Data-analysis software framework 2DMAT and its application to experimental measurements for two-dimensional material structures},
+  journal = {Computer Physics Communications},
+  volume = {280},
+  pages = {108465},
+  year = {2022},
+  issn = {0010-4655},
+  doi = {https://doi.org/10.1016/j.cpc.2022.108465},
+  url = {https://www.sciencedirect.com/science/article/pii/S0010465522001849},
+  author = {Yuichi Motoyama and Kazuyoshi Yoshimi and Izumi Mochizuki and Harumichi Iwamoto and Hayato Ichinose and Takeo Hoshi}
+}
+
+
+
+
+

バージョン履歴

+
    +

  • ODAT-SE

    +
      +

    • v3.0.0 : 2024-11-25

      • +
    +
    • +

  • 2DMAT

    +
      +

    • v2.1.0 : 2022-04-08

      • +

    • v2.0.0 : 2022-01-17

      • +

    • v1.0.1 : 2021-04-15

      • +

    • v1.0.0 : 2021-03-12

      • +

    • v0.1.0 : 2021-02-08

      • +
    +
    • +
+
+
+

主な開発者

+

ODAT-SEは以下のメンバーで開発しています.

+
    +

  • ODAT-SE v3.0.0 -

    +
      +

    • 本山 裕一 (東京大学 物性研究所)

      • +

    • 吉見 一慶 (東京大学 物性研究所)

      • +

    • 青山 龍美 (東京大学 物性研究所)

      • +

    • 星　 健夫 (核融合科学研究所)

      • +
    +
    • +

  • 2DMAT v2.0.0 -

    +
      +

    • 本山 裕一 (東京大学 物性研究所)

      • +

    • 吉見 一慶 (東京大学 物性研究所)

      • +

    • 岩本 晴道 (鳥取大学 大学院工学研究科)

      • +

    • 星　 健夫 (鳥取大学 大学院工学研究科)

      • +
    +
    • +

  • 2DMAT v0.1.0 -

    +
      +

    • 本山 裕一 (東京大学 物性研究所)

      • +

    • 吉見 一慶 (東京大学 物性研究所)

      • +

    • 星　 健夫 (鳥取大学 大学院工学研究科)

      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/objects.inv b/manual/v3.0.0/ja/objects.inv new file mode 100644 index 00000000..f56bb41e Binary files /dev/null and b/manual/v3.0.0/ja/objects.inv differ diff --git a/manual/v3.0.0/ja/output.html b/manual/v3.0.0/ja/output.html new file mode 100644 index 00000000..a9ae9810 --- /dev/null +++ b/manual/v3.0.0/ja/output.html @@ -0,0 +1,113 @@ + + + + + + + + 出力ファイル — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

出力ファイル

+

各種 Solver, Algorithm が出力するファイルについては、 順問題ソルバー および 探索アルゴリズム を参照してください。

+
+

共通ファイル

+
+

time.log

+

MPI のランク毎に計算にかかった総時間を出力します。 +各ランクのサブフォルダ以下に出力されます。 +計算の前処理にかかった時間、計算にかかった時間、計算の後処理にかかった時間について、 +prepare , run , post のセクションごとに記載されます。

+

以下、出力例です。

+
#prepare
+ total = 0.007259890999989693
+#run
+ total = 1.3493346729999303
+ - file_CM = 0.0009563499997966574
+ - submit = 1.3224223930001244
+#post
+ total = 0.000595873999941432
+
+
+
+
+

runner.log

+

MPI のランクごとに、ソルバー呼び出しに関するログ情報を出力します。 +各ランクのサブフォルダ以下に出力されます。 +入力で runner.log.interval パラメータが正の整数の時のみ出力されます。

+
    +

  • 1列目がソルバー呼び出しの通し番号、

    • +

  • 2列目が前回呼び出しからの経過時間、

    • +

  • 3列目が計算開始からの経過時間

    • +
+
# $1: num_calls
+# $2: elapsed_time_from_last_call
+# $3: elapsed_time_from_start
+
+1 0.0010826379999999691 0.0010826379999999691
+2 6.96760000000185e-05 0.0011523139999999876
+3 9.67080000000009e-05 0.0012490219999999885
+4 0.00011765699999999324 0.0013666789999999818
+5 4.965899999997969e-05 0.0014163379999999615
+6 8.666900000003919e-05 0.0015030070000000006
+   ...
+
+
+
+
+

status.pickle

+

algorithm.checkpoint が true の場合、MPI のランクごとに実行中の状態を出力します。 +各ランクのサブフォルダ以下に出力されます。実行を再開する場合に読み込まれます。 +ファイルの内容はアルゴリズムに依ります。

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/search.html b/manual/v3.0.0/ja/search.html new file mode 100644 index 00000000..1d3b6ab6 --- /dev/null +++ b/manual/v3.0.0/ja/search.html @@ -0,0 +1,79 @@ + + + + + + + 検索 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + + + + + +
+ + +

検索

+ + + + +

+ 複数の単語を検索すると、次を含む一致のみが表示されます +     すべての用語。 +

+ + +
+ + + +
+ + +
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/searchindex.js b/manual/v3.0.0/ja/searchindex.js new file mode 100644 index 00000000..80283dee --- /dev/null +++ b/manual/v3.0.0/ja/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"alltitles": {"(\u958b\u767a\u8005\u5411\u3051)\u30e6\u30fc\u30b6\u30fc\u5b9a\u7fa9\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u30fb\u30bd\u30eb\u30d0\u30fc": [[10, null]], "Affine": [[9, "affine"]], "Algorithm": [[8, "id1"]], "Algorithm \u306e\u5b9a\u7fa9": [[8, null]], "AlgorithmBase": [[8, "algorithmbase"]], "Annealed Importance Sampling (AIS) [1]": [[6, "annealed-importance-sampling-ais-1"]], "BayesData.txt": [[1, "bayesdata-txt"]], "ColorMap.txt": [[4, "colormap-txt"]], "Contents:": [[13, null]], "Domain \u306e\u5b9a\u7fa9": [[8, "domain"]], "Inequality": [[9, "inequality"]], "MeshGrid \u30af\u30e9\u30b9": [[8, "meshgrid"]], "Nelder-Mead \u6cd5 minsearch": [[5, null]], "Nelder-Mead\u6cd5\u306b\u3088\u308b\u6700\u9069\u5316": [[27, null]], "ODAT-SE \u306e\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [[19, null]], "ODAT-SE\u3068\u306f": [[15, "odat-se"]], "RANK/result.txt": [[2, "rank-result-txt"], [6, "rank-result-txt"]], "RANK/result_T#.txt": [[6, "rank-result-t-txt"]], "RANK/trial.txt": [[2, "rank-trial-txt"], [6, "rank-trial-txt"]], "RANK/trial_T#.txt": [[6, "rank-trial-t-txt"]], "Region \u30af\u30e9\u30b9": [[8, "region"]], "SimplexData.txt": [[5, "simplexdata-txt"]], "Solver \u306e\u5b9a\u7fa9": [[11, null]], "TrivialMapping": [[9, "trivialmapping"]], "Unlimited": [[9, "unlimited"]], "Welcome to ODAT-SE documentation!": [[13, null]], "[algorithm.bayes] \u30bb\u30af\u30b7\u30e7\u30f3": [[1, "algorithm-bayes"]], "[algorithm] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "algorithm"]], "[algorithmparam] \u30bb\u30af\u30b7\u30e7\u30f3": [[1, "algorithmparam"]], "[base] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "base"]], "[exchange] \u30bb\u30af\u30b7\u30e7\u30f3": [[2, "id3"]], "[minimize] \u30bb\u30af\u30b7\u30e7\u30f3": [[5, "minimize"]], "[pamc] \u30bb\u30af\u30b7\u30e7\u30f3": [[6, "id3"]], "[param] \u30bb\u30af\u30b7\u30e7\u30f3": [[2, "param"], [4, "param"], [5, "param"], [6, "param"]], "[runner.limitation] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "runner-limitation"]], "[runner.log] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "runner-log"]], "[runner.mapping] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "runner-mapping"]], "[runner] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "runner"]], "[solver] \u30bb\u30af\u30b7\u30e7\u30f3": [[14, "solver"]], "analytical \u30bd\u30eb\u30d0\u30fc": [[17, null]], "base \u306b\u3064\u3044\u3066": [[9, "base"]], "best_result.txt": [[2, "best-result-txt"], [6, "best-result-txt"]], "fx.txt": [[6, "fx-txt"]], "odatse.Info": [[9, "odatse-info"]], "odatse.Limitation": [[9, "odatse-limitation"]], "odatse.Mapping": [[9, "odatse-mapping"]], "odatse.Runner": [[9, "odatse-runner"]], "odatse_neighborlist": [[20, "odatse-neighborlist"]], "population annealing (PA) [2]": [[6, "population-annealing-pa-2"]], "res.txt": [[5, "res-txt"]], "result_T#.txt": [[2, "result-t-txt"]], "runner.log": [[16, "runner-log"]], "status.pickle": [[16, "status-pickle"]], "time.log": [[16, "time-log"]], "\u304a\u554f\u3044\u5408\u308f\u305b": [[7, null]], "\u306f\u3058\u3081\u306b": [[15, null]], "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u88dc\u52a9\u30d5\u30a1\u30a4\u30eb": [[1, "id3"], [2, "id4"], [4, "id3"], [6, "id5"]], "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u89e3\u8aac": [[1, "id7"], [2, "id9"], [6, "id10"]], "\u30a2\u30f3\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [[19, "id4"]], "\u30b0\u30ea\u30c3\u30c9\u578b\u63a2\u7d22": [[26, null]], "\u30b0\u30ea\u30c3\u30c9\u578b\u63a2\u7d22 mapper": [[4, null]], "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a1\u30a4\u30eb\u306e\u5834\u6240": [[21, "id2"], [22, "id2"], [25, "id2"], [26, "id2"], [27, "id1"], [28, "id2"]], "\u30b9\u30c6\u30c3\u30d7\u6570\u306b\u3064\u3044\u3066": [[6, "id4"]], "\u30c0\u30a6\u30f3\u30ed\u30fc\u30c9\u30fb\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [[19, "id2"]], "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb": [[23, null]], "\u30d0\u30fc\u30b8\u30e7\u30f3\u5c65\u6b74": [[15, "id3"]], "\u30d9\u30a4\u30ba\u6700\u9069\u5316": [[21, null]], "\u30d9\u30a4\u30ba\u6700\u9069\u5316 bayes": [[1, null]], "\u30d9\u30f3\u30c1\u30de\u30fc\u30af\u95a2\u6570\u30bd\u30eb\u30d0\u30fc": [[29, "id2"]], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u306b\u3088\u308b\u63a2\u7d22": [[28, null]], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 pamc": [[6, null]], "\u30de\u30eb\u30b3\u30d5\u9023\u9396\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5": [[2, "id10"]], "\u30e1\u30c3\u30b7\u30e5\u5b9a\u7fa9\u30d5\u30a1\u30a4\u30eb": [[1, "id4"], [2, "id5"], [4, "id4"], [6, "id6"]], "\u30e9\u30a4\u30bb\u30f3\u30b9": [[15, "id2"]], "\u30ea\u30b9\u30bf\u30fc\u30c8": [[1, "id6"], [2, "id8"], [4, "id6"], [5, "id5"], [6, "id9"]], "\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5": [[2, "id12"]], "\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22": [[22, null]], "\u4e3b\u306a\u958b\u767a\u8005": [[15, "id4"]], "\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 exchange": [[2, null]], "\u4f7f\u3044\u65b9": [[20, "id2"]], "\u5165\u529b\u30d1\u30e9\u30e1\u30fc\u30bf": [[1, "id2"], [2, "id2"], [4, "id2"], [5, "id3"], [6, "id2"], [17, "id1"]], "\u5165\u529b\u30d5\u30a1\u30a4\u30eb": [[14, null]], "\u5165\u529b\u30d5\u30a1\u30a4\u30eb\u306e\u8aac\u660e": [[21, "id3"], [22, "id3"], [25, "id3"], [26, "id3"], [27, "id2"], [28, "id3"]], "\u5171\u901a\u30d5\u30a1\u30a4\u30eb": [[16, "id2"]], "\u5171\u901a\u4e8b\u9805": [[9, null]], "\u51fa\u529b\u30d5\u30a1\u30a4\u30eb": [[1, "id5"], [2, "id7"], [4, "id5"], [5, "id4"], [6, "id8"], [16, null]], "\u5236\u7d04\u5f0f\u3092\u9069\u7528\u3057\u305f\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22": [[25, null]], "\u524d\u6e96\u5099": [[1, "id1"], [2, "id1"], [4, "id1"], [5, "id2"], [6, "id1"]], "\u53c2\u8003\u6587\u732e": [[6, "id12"]], "\u554f\u984c\u3068\u76ee\u7684": [[6, "id11"]], "\u5b9f\u884c\u65b9\u6cd5": [[12, null], [19, "id3"]], "\u5b9f\u884c\u74b0\u5883\u30fb\u5fc5\u8981\u306a\u30d1\u30c3\u30b1\u30fc\u30b8": [[19, "id1"]], "\u63a2\u7d22\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0": [[3, null]], "\u89e3\u6790\u95a2\u6570\u306e\u6700\u5c0f\u5316\u554f\u984c": [[24, null]], "\u8a08\u7b97\u306e\u5b9f\u884c": [[21, "id4"], [22, "id4"], [25, "id4"], [26, "id4"], [27, "id3"], [28, "id4"]], "\u8a08\u7b97\u7d50\u679c\u306e\u53ef\u8996\u5316": [[21, "id5"], [22, "id5"], [25, "id5"], [26, "id5"], [27, "id4"], [28, "id5"]], "\u8b1d\u8f9e": [[0, null]], "\u8fd1\u508d\u30ea\u30b9\u30c8\u5b9a\u7fa9\u30d5\u30a1\u30a4\u30eb": [[2, "id6"], [6, "id7"]], "\u95a2\u9023\u30c4\u30fc\u30eb": [[20, null]], "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc": [[18, null]], "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc\u306e\u8ffd\u52a0": [[29, null], [29, "id3"]]}, "docnames": ["acknowledgement", "algorithm/bayes", "algorithm/exchange", "algorithm/index", "algorithm/mapper_mpi", "algorithm/minsearch", "algorithm/pamc", "contact", "customize/algorithm", "customize/common", "customize/index", "customize/solver", "customize/usage", "index", "input", "introduction", "output", "solver/analytical", "solver/index", "start", "tool", "tutorial/bayes", "tutorial/exchange", "tutorial/index", "tutorial/intro", "tutorial/limitation", "tutorial/mapper", "tutorial/minsearch", "tutorial/pamc", "tutorial/solver_simple"], "envversion": {"sphinx": 64, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2}, "filenames": ["acknowledgement.rst", "algorithm/bayes.rst", "algorithm/exchange.rst", "algorithm/index.rst", "algorithm/mapper_mpi.rst", "algorithm/minsearch.rst", "algorithm/pamc.rst", "contact.rst", "customize/algorithm.rst", "customize/common.rst", "customize/index.rst", "customize/solver.rst", "customize/usage.rst", "index.rst", "input.rst", "introduction.rst", "output.rst", "solver/analytical.rst", "solver/index.rst", "start.rst", "tool.rst", "tutorial/bayes.rst", "tutorial/exchange.rst", "tutorial/index.rst", "tutorial/intro.rst", "tutorial/limitation.rst", "tutorial/mapper.rst", "tutorial/minsearch.rst", "tutorial/pamc.rst", "tutorial/solver_simple.rst"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"!/": 25, "!=": 29, "\"\"": [14, 29], "\"\"\"": 29, "\")": [5, 14], "\",": [1, 9, 15], "\":": 29, "\"]": [8, 9, 11], "\"analytical": 29, "\"continue": [1, 2, 4, 6, 8], "\"data": 15, "\"error": 29, "\"exchange": 25, "\"initial": [1, 2, 4, 6], "\"initialize": 8, "\"post": 8, "\"prepare": 8, "\"resume": [1, 2, 4, 6, 8], "\"run": 8, "\"status": 14, "#prepare": 16, "#step": [1, 5, 21], "$home": 19, "%.": [22, 28], "&..": 14, "&=": 6, "&\\": 6, "')": 6, "( f": 6, "(\"": 9, "()": [8, 9, 11, 12], "(-": [2, 17], "(\\": [1, 2, 17], "(_": 7, "(a": [5, 6], "(allvecs": 27, "(base": 9, "(booth": 29, "(cls": 8, "(exchange": 14, "(info": [8, 12], "(input": 12, "(k": 6, "(leed": [14, 15], "(method": 5, "(odatse": [8, 11, 12], "(rheed": 14, "(self": [8, 9, 11], "(solver": 12, "(sxrd": [14, 15], "(total": 15, "(w": 6, "(x": [3, 4, 6, 8, 9, 17, 18, 21, 22, 24, 28, 29], "(xs": 29, "(z": [6, 28], "(\u03b2": 6, "(\u3064\u307e\u308a": 6, "(\u4f8b": 14, "(\u5c71": 2, "(\u9006": 28, "(\u967d": 14, ") w": 2, ")\"": 1, "))": 9, "),": [11, 28], ").": [6, 15], ")/": 6, "):": [6, 8, 11, 12, 27], ")=": 24, ")[": 15, ")\\": [1, 6, 17], ")^": [17, 24, 29], ")f": 6, ")}": [2, 6], ")\u3001": [2, 6, 28], ")\u3002": [1, 2, 6, 25, 28], "*)": 17, "**": 29, "+ a": 14, "+ b": 14, "+ x": 25, "+b": [9, 14, 25], "+y": [17, 24, 29], ", \"": 1, ", w": 6, ",:": 6, ",n": [6, 14], "- \\": 17, "- x": [17, 25], "--": [19, 21, 22], "-1": 6, "->": [8, 9, 11, 15, 29], "-\\": [2, 6], "-allow": 20, "-allpairs": 20, "-analysis": 15, "-center": 19, "-check": 20, "-cont": [1, 2, 4, 6], "-dev": [7, 19], "-dimensional": 15, "-energy": 15, "-f": 2, "-factor": [1, 5, 21], "-hasting": 2, "-hill": 24, "-in": 25, "-init": [1, 2, 4, 6], "-jarzynski": [6, 28], "-leed": 19, "-mail": 7, "-mead": [3, 13, 14, 15, 19, 21, 22, 23, 26, 28, 29], "-o": [20, 21], "-output": 20, "-oversubscribe": [22, 25, 28], "-q": 20, "-quiet": 20, "-r": 20, "-radius": 20, "-reflection": 15, "-resetrand": 8, "-resume": [1, 2, 4, 6], "-rheed": 14, "-se": [1, 2, 5, 7, 9, 12, 14, 22, 23, 24, 27, 29], "-selfloop": 20, "-se\u30d1\u30c3\u30b1\u30fc\u30b8": [21, 22, 26], "-str": 19, "-sxrd": 19, "-tokyo": 7, "-trhepd": 14, "-u": 20, "-unit": 20, "-user": 19, ".\"": 9, ".,": 15, "..": [2, 6, 21, 22, 25, 26, 27, 28, 29], "...": [1, 2, 4, 6, 11, 14, 16, 20, 21, 22, 25, 26, 27, 28, 29], ".]": 27, "._": 8, ".__": [8, 11], ".a": [5, 15], ".ac": 7, ".algorithm": [8, 12], ".algorithmbase": [8, 12], ".argv": 12, ".base": [8, 11], ".bayes": 21, ".checkpoint": [8, 16], ".com": [15, 19], ".comm": 8, ".cpc": 15, ".dat": 27, ".dimension": [8, 14], ".domain": 8, ".exchange": [22, 25], ".expanduser": 9, ".from": 12, ".function": 29, ".generator": 8, ".get": 9, ".info": [8, 11, 12], ".interval": 16, ".j": 15, ".jp": 7, ".k": 5, ".label": 8, ".limitation": [23, 25], ".log": [26, 27, 28], ".main": 12, ".meshgrid": 8, ".minimize": 5, ".mpicomm": 8, ".mpirank": [8, 11], ".mpisize": 8, ".ndarray": [9, 11, 29], ".optimize": 5, ".org": 15, ".output": [8, 11], ".pamc": 28, ".param": [1, 4, 5, 8, 21, 22, 25, 26, 27, 28, 29], ".path": [8, 9], ".pdf": [21, 27], ".pickle": 14, ".png": 26, ".post": 8, ".prepare": 8, ".proc": [8, 11], ".py": [19, 20, 21, 22, 25, 26, 27, 28, 29], ".random": 8, ".region": 8, ".rng": 8, ".root": [8, 11], ".run": 8, ".runner": [8, 12], ".sciencedirect": 15, ".set": 29, ".sh": [21, 22, 25, 26, 27, 28], ".shape": 29, ".solver": [11, 12], ".solverbase": [11, 12], ".submit": 8, ".timer": 8, ".toml": [19, 21, 22, 25, 26, 27, 28, 29], ".txt": [20, 21, 22, 25, 26, 27, 28], ".u": 7, "/ \\": 6, "/.": 19, "/..": [21, 22, 25, 26, 27, 28], "/\\": 6, "/actions": 21, "/analytical": [21, 22, 25, 26, 27, 28, 29], "/article": 15, "/bash": 25, "/bayes": 21, "/bayesdata": 21, "/best": [25, 28], "/colormap": 26, "/exchange": 22, "/fx": 28, "/issp": 19, "/limitation": 25, "/mapper": 26, "/minsearch": 27, "/odat": 19, "/odatse": [19, 20, 21, 22, 25, 26, 27, 28, 29], "/pamc": 28, "/pii": 15, "/plot": [21, 22, 27], "/res": [21, 22, 27], "/result": 22, "/s": 15, "/science": 15, "/solver": 29, "/src": [21, 22, 25, 26, 27, 28], "/t": [6, 28], "/z": [6, 28], "10": 15, "11": 15, "1e": 5, "1\u3064": [6, 22], "2d": [25, 26], "2dmap": 28, "2dmat": [7, 15], "2x": 29, "2y": 29, "2\u3064": [6, 25], "3\u3064": [6, 8], "4py": [1, 2, 4, 6, 8, 19], "4\u3064": [9, 14], "5\u3064": 23, ":/": [15, 19], ":]": 6, "=\n\\": 6, "= \"": 29, "= (": [17, 24, 29], "= \\": [2, 6], "= f": [6, 17], "= p": 2, "= w": 6, "=\"": [5, 21, 22], "=$": 25, "=(": 11, "=\\": 22, "=ax": 9, "=info": 8, "=output": [21, 22, 27], "=runner": 8, "={": 29, ">=": 19, ">_": 25, "@article": 15, "[\"": [8, 9, 11], "[-": [6, 17], "[1": [6, 15, 24], "[2": [6, 15], "[3": [6, 15], "[4": 15, "[5": 15, "[6": 15, "[7": 15, "[8": 15, "[9": 15, "[\\": 17, "[]": 14, "[algorithm": [21, 22, 25, 26, 27, 28], "[all": 19, "[base": [21, 22, 25, 26, 27, 28, 29], "[i": 6, "[int": 9, "[mpi": 8, "[runner": [21, 22, 23, 25, 26, 27, 28], "[solver": [1, 4, 5, 21, 22, 25, 26, 27, 28, 29], "[step": 27, "[str": 8, "\\\nx": 25, "\\\\": [6, 14], "\\begin": 6, "\\beta": [2, 6], "\\delta": 2, "\\frac": 6, "\\int": 6, "\\langle": 6, "\\left": [2, 6, 17], "\\log": [6, 28], "\\mathbf": 3, "\\min": 2, "\\rangle": 6, "\\right": 17, "\\tilde": 6, "\\to": 9, "\\vec": [1, 2], "\\}": [1, 2, 6, 22], "])": [6, 9], "],": [6, 14, 15, 25], "].": 29, "]:": 27, "]]": [14, 25], "]}": 29, "^*": 17, "^{": [2, 6], "__": [7, 8, 9, 11, 29], "_a": [14, 25], "_action": [1, 21], "_annealing": [6, 28], "_b": [14, 25], "_basis": [1, 21], "_call": [9, 16], "_calls": 16, "_cm": 16, "_colormap": 26, "_delta": 14, "_dict": 9, "_dir": [8, 9, 11, 14, 21, 22, 25, 26, 27, 28, 29], "_exchange": [2, 22, 25], "_file": [8, 9, 12, 14], "_from": [6, 16], "_function": 29, "_himmel": [21, 22, 27], "_i": [6, 17], "_init": [8, 29], "_input": 14, "_interval": [6, 8, 14], "_k": 6, "_last": 16, "_limitation": 25, "_list": [1, 2, 4, 5, 6, 8, 14, 21, 22, 25, 26, 27, 28, 29], "_main": [19, 21, 22, 25, 26, 27, 28, 29], "_max": [1, 21], "_mode": [1, 2, 4, 6, 8], "_mpi": [1, 4, 23], "_n": [6, 28], "_name": [17, 21, 22, 25, 26, 27, 28, 29], "_neighborlist": [2, 6, 13], "_num": [1, 6, 21], "_path": [1, 2, 4, 6], "_per": [2, 6, 22, 28], "_post": 8, "_prepare": 8, "_probes": [1, 21], "_proc": [2, 6, 22, 28], "_rand": [1, 21], "_rank": 14, "_replicas": 6, "_result": [14, 22, 25, 28], "_run": 8, "_sample": 25, "_scale": 5, "_search": 8, "_simplex": 5, "_split": 8, "_start": 16, "_steps": [8, 14], "_t": [22, 28], "_time": 16, "_txxx": 28, "_walkers": 8, "_world": 8, "_{": [2, 6, 14, 17, 25], "_{i": 1, "abics": 0, "absolute": 9, "acceptance": [6, 28], "ackley": 17, "acquition": 1, "acta": 15, "action": [1, 21], "aip": [6, 15], "akimoto": 15, "al": 15, "algorithm": [1, 2, 3, 6, 9, 10, 11, 12, 13, 14, 16, 19, 21, 22, 25, 26, 27, 28, 29], "algorithmparam": 1, "all": 15, "allvecs": 27, "analysis": 15, "analytical": [13, 14, 18, 21, 22, 24, 25, 26, 27, 28, 29], "ancestor": [6, 28], "and": [6, 15, 25], "annealing": 2, "aoyama": 15, "appl": 15, "application": 15, "applied": [15, 24], "args": [8, 9, 11], "at": [7, 29], "author": 15, "automated": 15, "aw": 6, "ax": [14, 25], "barbieri": 15, "base": [13, 14], "bayes": [3, 13, 14, 21, 23], "bayesian": 1, "begin": 14, "best": [21, 22, 25], "beta": 6, "bibtex": 15, "big": 6, "bin": [20, 25], "bmax": [2, 6, 28], "bmin": [2, 6, 28], "bo": 1, "bool": [9, 14], "booth": 29, "burn": 25, "but": 29, "by": 15, "carlo": [2, 11], "cd": [21, 22, 25, 26, 27, 28], "cdots": 6, "checkpoint": 14, "class": [8, 11, 12], "clone": 19, "co": [14, 25], "colormap": 26, "colormapfig": 26, "communications": 15, "complex": 15, "computer": 15, "computing": [6, 15], "conf": [6, 15], "continue": [1, 2, 4], "copyright": 15, "cos": 17, "current": [21, 27], "data": 15, "def": [11, 29], "default": [1, 2, 5, 6, 14, 20], "define": 12, "delta": 2, "determination": 15, "dict": [8, 9, 12], "diff": 25, "differ": 25, "diffraction": 15, "dimension": [1, 2, 4, 5, 6, 14, 21, 22, 25, 26, 27, 28, 29], "do": [8, 21, 22, 25, 26, 27, 28], "doi": 15, "dots": 6, "downhill": 5, "draw": 6, "echo": 25, "ei": 1, "elapsed": 16, "elif": 29, "else": 25, "end": [6, 14], "engineering": 15, "eq": 25, "equiv": 6, "error": [6, 28], "et": 15, "evaluate": 11, "evaluations": [27, 29], "exchange": [3, 13, 14, 22, 23, 25], "exp": [2, 6, 17], "expected": 1, "expects": 29, "experimental": 15, "failed": 25, "false": [14, 25], "fatol": 5, "fi": 25, "file": 16, "filename": 14, "fix": 6, "float": [9, 11, 29], "for": [6, 15], "forall": 17, "format": [21, 22], "frac": [2, 6, 17], "framework": 15, "from": [8, 9], "function": [1, 17, 21, 22, 25, 26, 27, 28, 29], "funtion": 17, "fx": [2, 5, 8, 21, 22, 25, 27, 28], "git": 19, "github": [7, 19], "global": 29, "hanada": 15, "harumichi": 15, "has": 29, "hayato": 15, "high": 15, "himmelblau": [21, 22, 24, 25, 26, 27, 28, 29], "himmerblau": 17, "hisada": 15, "hist": 25, "histogram": 25, "hoshi": 15, "hove": 15, "https": [15, 19], "hukushima": [6, 15], "hyodo": 15, "iba": [6, 15], "ichimiya": 15, "ichinose": 15, "if": [6, 25, 29], "import": [8, 11, 12], "improvement": 1, "in": 6, "index": 22, "info": [8, 9, 11, 12], "init": [8, 11], "initial": [2, 5, 6, 27, 29], "initialize": 8, "input": [12, 19, 21, 22, 25, 26, 27, 28, 29], "install": [1, 2, 4, 5, 6, 19], "int": [1, 6, 8, 9, 11], "interval": [1, 6, 14, 21, 26, 27, 28], "issn": 15, "issp": 7, "issues": 7, "it": 29, "iteration": [26, 27], "iterations": [27, 29], "its": 15, "iwamoto": 15, "izumi": 15, "japan": 15, "jjap": 15, "journal": 15, "judge": 9, "kawata": 15, "kazuyoshi": 15, "langle": 6, "le": 2, "leed": [14, 15, 19], "left": [6, 14, 17], "len": 27, "lett": 15, "license": 15, "limitation": [8, 9, 14, 25], "linear": 1, "list": 8, "local": [14, 19], "log": [6, 14, 21, 22, 25, 26, 27, 28], "logging": 14, "machta": [6, 15], "main": 8, "make": 26, "mapper": [1, 3, 8, 13, 14, 23, 26], "mapping": [9, 14], "materer": 15, "material": 15, "mathrm": 6, "max": [1, 2, 4, 5, 6, 14, 21, 22, 25, 26, 27, 28, 29], "maxfev": 5, "maxiter": 5, "mcgraw": 24, "mcmc": [2, 6], "mean": [6, 28], "measurements": 15, "mesh": [1, 2, 4, 6], "meshdata": 20, "method": 6, "metropolis": 2, "mh": 2, "mh\u6cd5": 2, "min": [1, 2, 4, 5, 6, 8, 14, 21, 22, 25, 26, 27, 28, 29], "minimize": 5, "minimum": 29, "minsearch": [2, 3, 13, 14, 21, 22, 23, 26, 27, 28, 29], "mochizuki": 15, "model": 1, "monte": [2, 11], "moritz": 15, "motoyama": 15, "mozilla": 15, "mpi": [1, 2, 4, 6, 8, 11, 14, 16, 19, 20, 22, 25, 26, 28], "mpiexec": [22, 25, 26, 28], "mpl": 15, "mukainakano": 15, "nakatani": 15, "name": [14, 21, 22, 25, 26, 27, 28, 29], "ne": 14, "neal": [6, 15, 28], "nealder": 23, "neighborlist": [2, 6, 20], "nelder": [3, 13, 14, 15, 19, 21, 22, 23, 26, 28, 29], "nemoto": 15, "ni": 3, "none": 8, "nonlinear": 24, "np": [8, 9, 11, 22, 25, 26, 28, 29], "nprocs": [2, 6, 11, 22, 25, 28], "nreplica": [2, 6, 22, 28], "nthreads": 11, "num": [1, 4, 8, 16, 21, 26], "number": [6, 28], "numpy": [11, 14, 19], "numstep": [22, 25], "numsteps": [2, 6, 22, 25, 28], "numt": 6, "odat": [1, 2, 5, 7, 9, 12, 14, 21, 22, 23, 24, 26, 27, 29], "odatse": [1, 2, 4, 6, 8, 11, 12, 13, 19], "of": [1, 6, 15, 28], "one": 29, "open": [15, 25], "openmpi": [22, 28], "optimization": [1, 27], "optional": [8, 19], "or": 20, "output": [9, 11, 14, 20, 21, 22, 25, 26, 27, 28, 29], "over": 15, "oversubscribe": 25, "pages": 15, "pamc": [3, 13, 14, 23, 28], "parallel": 2, "param": [2, 4, 5, 6, 8], "parameter": 21, "pass": [8, 11, 12, 25], "path": 8, "pathlib": [8, 9], "pc": [21, 22, 25, 26, 27, 28], "phys": 15, "physbo": [1, 19, 21], "physics": 15, "pi": [1, 17], "pip": [1, 2, 4, 5, 6, 19, 20], "plot": [21, 24, 26, 27, 28], "png": [22, 28], "pol": 15, "positron": 15, "post": [8, 16], "pre": 6, "prepare": [8, 16], "probability": 1, "proc": [6, 11, 15], "procs": 11, "prod": 6, "programming": 24, "public": 15, "pypi": 19, "python": [1, 2, 4, 5, 6, 19, 20, 21, 22, 25, 26, 27, 28, 29], "quad": 17, "quadratics": 17, "radius": 20, "raise": 29, "random": [1, 21], "range": 6, "rangle": 6, "rank": [22, 25, 28], "ratio": [6, 28], "receives": 29, "ref": 25, "replica": [2, 28], "replicas": [6, 28], "reports": 15, "res": [22, 25, 28], "resample": 6, "resampling": 6, "reserved": 15, "result": [6, 12, 22, 25, 28], "resume": 1, "return": 29, "rev": 15, "reweighting": 6, "right": [2, 6, 14, 17], "rights": 15, "rng": 8, "root": [8, 9, 11, 14], "rosenbrock": 17, "rous": 15, "run": [1, 2, 4, 6, 8, 16], "runner": [8, 9, 11, 12, 13, 14, 25, 26, 27, 28], "runtimeerror": 29, "sample": [21, 22, 25, 26, 27, 28], "sampling": 1, "science": 15, "scipy": [5, 19], "score": [1, 21], "seed": [14, 21, 22, 25, 26, 27, 28, 29], "self": [8, 9, 11, 29], "series": 15, "set": [8, 11], "sim": [2, 14], "simplex": 5, "simplexdata": 27, "simulated": 2, "skip": 22, "skipped": 29, "soc": 15, "software": 15, "solution": 29, "solver": [3, 9, 10, 12, 13, 14, 16, 17, 18, 19, 21, 22, 25, 26, 27, 28, 29], "somorjai": 15, "sqrt": 17, "src": [19, 20, 27, 29], "standard": [6, 28], "starke": 15, "statistics": [6, 15], "step": [2, 5, 6, 8, 11, 21, 22, 25, 27, 28], "store": 8, "str": [8, 11], "string": [1, 4, 5, 14, 17], "structures": 15, "submit": [9, 16], "successfully": 27, "suffix": 14, "sugiyama": 15, "sum": [2, 6, 17], "sumitani": 15, "super": [8, 11], "surface": 15, "swendsen": 15, "sxrd": [14, 19], "sys": 12, "tajiri": 15, "takahashi": 15, "takeo": 15, "tamura": 15, "tanaka": 15, "tee": [21, 22, 25, 26, 27, 28], "tempering": 2, "terayama": 15, "terminated": 27, "test": 25, "text": 6, "th": 21, "the": 15, "then": 25, "thompson": 1, "tilde": 6, "times": 14, "title": 15, "tlogspace": [2, 6, 22, 25, 28], "tmax": [2, 6, 22, 25, 28], "tmin": [2, 6, 22, 25, 28], "tnum": [6, 28], "to": [9, 15], "tokyo": 15, "toml": [9, 12, 14, 27], "tomli": 19, "tool": 15, "total": 16, "tqdm": 20, "transfer": 6, "trhepd": [14, 15, 19], "trial": [2, 6, 22, 25, 28], "true": [2, 6, 9, 16, 22, 25, 28], "ts": [1, 21], "tsuda": 15, "tuple": [9, 11], "two": 15, "txt": [22, 28], "ueno": 15, "uninstall": 19, "unit": [5, 20, 25], "university": 15, "update": 14, "url": 15, "value": [21, 27], "van": 15, "vec": [1, 2, 17], "ver": 19, "version": 15, "voegeli": 15, "volume": 15, "walker": [2, 6, 8, 22, 25, 28], "wander": 15, "wang": 15, "weight": [6, 28], "work": 9, "write": 14, "www": 15, "xatol": 5, "xcol": [21, 22, 27], "xs": 29, "xxx": 28, "ycol": [21, 22, 27], "year": 15, "yoshimi": 15, "your": 12, "yuichi": 15, "zhang": 15, "{\\": [1, 2, 6, 17], "{d": 6, "{f": [1, 2, 6], "{g": 6, "{matrix": 14, "{motoyama": 15, "{split": 6, "{t": [2, 6], "{tnum": 6, "{w": 2, "{x": [1, 2, 3, 6, 17], "{z": 6, "| \\": 2, "}'": 2, "}(": 6, "})": [1, 2, 6, 17], "},": [2, 6, 15], "}-": 6, "}=": 6, "}\\": [2, 6, 17], "}^": [1, 6, 17], "}_": [1, 2, 6], "}_{": 1, "}x": 6, "}xa": 6, "}{": [2, 6, 17], "}{\\": 6, "}{f": 6, "}{t": 6, "}{w": 2, "}}": [2, 6], "\u03b2[": 6, "\u3001(": 2, "\u3001[": 14, "\u3001\u300c": 2, "\u3002(": [6, 21, 22, 25, 26, 27, 28, 29], "\u3002)": [6, 21, 22, 25, 26, 27, 28], "\u3002himmelblau": 27, "\u3002set": 11, "\u3002step": 11, "\u3002version": 15, "\u3002\u307e\u305f": [9, 14], "\u3002\u7a7a": 14, "\u300c\u307c\u3084\u3051": 2, "\u300d(": [2, 6], "\u300d\uff0c": 15, "\u3042\u3068": [20, 21, 25], "\u3042\u307e\u308a": 1, "\u3042\u3089": 9, "\u3042\u3089\u304b\u3058\u3081": [1, 2, 4, 5, 6, 20], "\u3042\u308a": [1, 2, 4, 5, 6, 8, 10, 14, 29], "\u3042\u308b": [1, 2, 4, 5, 7, 8, 12, 14, 21, 22, 25, 26, 27, 28], "\u3042\u308b\u3044": 14, "\u3044\u304d": 2, "\u3044\u304f": [2, 15], "\u3044\u304f\u3064\u304b": [2, 10], "\u3044\u307e\u305b": [4, 5], "\u3044\u308b": [1, 2, 4, 6, 7, 8, 9, 14, 21, 22, 24, 25, 26, 27, 28, 29], "\u3046\u3061": [2, 6], "\u304a\u3044": [1, 2, 4], "\u304a\u304b\u3052": 2, "\u304a\u304d": [2, 21], "\u304a\u304f": [1, 2, 4, 5, 6], "\u304a\u3051\u308b": [6, 26, 28], "\u304a\u3059\u3059\u3081": 2, "\u304a\u3059\u3059\u3081\u3057": 5, "\u304a\u3088\u3073": [0, 1, 6, 8, 10, 14, 15, 16, 22, 25, 28], "\u304a\u308a": [1, 4, 15], "\u304a\u554f\u3044": 13, "\u304b\u304b\u3063": [8, 16], "\u304b\u304b\u308b": 1, "\u304b\u3051\u308b": 14, "\u304b\u3069": 14, "\u304b\u3069\u3046": 6, "\u304b\u306a\u3089": 2, "\u304b\u3082": 1, "\u304b\u3089": [1, 2, 4, 5, 6, 8, 9, 11, 14, 15, 16, 18, 19, 20, 22, 24, 25, 27, 29], "\u304c\u308f\u304b\u308a": [2, 21, 28], "\u304f\u3060": [1, 2, 5, 6, 7, 8, 9, 14, 15, 16, 19, 21, 22, 25, 26, 27, 28, 29], "\u3050\u3089\u3044": 2, "\u3053\u3046\u3057": 1, "\u3053\u3053": [6, 21, 22, 25, 26, 27, 28], "\u3053\u3053\u304b\u3089": 2, "\u3053\u3053\u3067": [6, 14, 29], "\u3053\u305d": 1, "\u3053\u3061\u3089": 7, "\u3053\u3068": [1, 2, 4, 5, 6, 7, 9, 10, 12, 14, 15, 19, 20, 21, 22, 25, 26, 27, 28, 29], "\u3053\u306e": [0, 2, 5, 6, 8, 12, 15, 21, 22, 23, 25, 26, 27, 28, 29], "\u3053\u308c": [1, 6, 27, 29], "\u3053\u308c\u3089": [1, 5, 10, 19, 20, 23, 25], "\u3054\u3068": [1, 2, 6, 8, 11, 14, 16, 22, 26, 28], "\u3055\u3044": [1, 2, 5, 6, 7, 8, 9, 14, 15, 16, 19, 21, 22, 25, 26, 27, 28, 29], "\u3055\u3066": 6, "\u3055\u3089\u306b": 28, "\u3057\u3065\u3089\u3044": 7, "\u3057\u3066": [2, 7], "\u3057\u307e\u3044": 6, "\u3057\u307e\u3059": [11, 14, 21, 27], "\u3057\u3084\u3059\u3044": 1, "\u3057\u308c": 1, "\u3059\u3067": 1, "\u3059\u3079": 14, "\u3059\u3079\u3066": 20, "\u3059\u308b": [1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 23, 25, 26, 27, 28, 29], "\u305a\u3064": 2, "\u305a\u3089\u3059": 5, "\u305b\u304f": 7, "\u305b\u308b": [2, 10], "\u305d\u3046": [2, 6], "\u305d\u3053": 6, "\u305d\u3057\u3066": 2, "\u305d\u306e": [1, 2, 4, 5, 6, 7, 8, 9, 14, 21, 22, 25, 26, 27, 28, 29], "\u305d\u306e\u3059\u3079\u3066": 4, "\u305d\u306e\u5f8c": 5, "\u305d\u308c": [2, 22, 25, 28], "\u305d\u308c\u305e\u308c": [1, 2, 4, 5, 6, 8, 28], "\u305e\u308c": 28, "\u305f\u3044": [18, 25, 27], "\u305f\u3044\u304f\u3064\u304b": 1, "\u305f\u304b": [21, 25], "\u305f\u3060\u304d": 0, "\u305f\u3068\u3048": [2, 29], "\u305f\u306a": 6, "\u305f\u3081": [2, 5, 6, 7, 8, 9, 10, 14, 15, 21, 22, 23, 25, 26, 27, 28, 29], "\u305f\u3089": 2, "\u305f\u308a": 2, "\u3060\u3051": [1, 2, 6, 20], "\u3060\u3055\u3044": [5, 7, 11, 14, 20], "\u3064\u304e": 29, "\u3064\u3051\u308b": 19, "\u3064\u307e\u308a": 9, "\u3067\u304d": [1, 2, 6, 9, 11, 12, 14, 19, 20, 22, 25, 26, 28], "\u3067\u304d\u308b": [2, 5, 6, 23, 25, 29], "\u3067\u304f\u304f\u3063": 20, "\u3067\u3059": [1, 2, 4, 5, 6, 8, 9, 11, 12, 14, 15, 16, 17, 19, 20, 21, 22, 24, 25, 26, 27, 28, 29], "\u3067\u306e": 1, "\u3067\u3082\u3063\u3068": 6, "\u3068\u3044\u3046": [2, 5, 6, 8, 9, 14, 15, 20], "\u3068\u304a\u3044": 2, "\u3068\u304a\u308a": [1, 2, 4, 6], "\u3068\u304b\u3051": 6, "\u3068\u304b\u3051\u308b": 6, "\u3068\u304d": [1, 2, 4, 6, 28], "\u3068\u3057": [2, 15, 29], "\u3068\u3057\u3066": [1, 2, 4, 5, 6, 8, 9, 11, 14, 15, 19, 20, 23, 24, 25, 26, 29], "\u3068\u3059\u308b": [2, 19], "\u3068\u305d\u306e": 21, "\u3068\u3064": [5, 28], "\u3068\u306a\u308b": [2, 14], "\u3068\u306e": 6, "\u3068\u3082": [8, 14], "\u3068\u3082\u306b": [22, 25], "\u3068\u3082\u547c\u3070": 2, "\u3068\u308a": [6, 11], "\u3068\u308c": 22, "\u3068\u8868\u305b": 6, "\u3069\u3046": [1, 2], "\u3069\u3053": [22, 26, 28], "\u3069\u3061\u3089\u304b": [2, 6], "\u3069\u308c": [2, 6], "\u306a\u3044": [1, 2, 4, 6, 8, 9, 11, 14, 25], "\u306a\u3048": 29, "\u306a\u304a": [1, 19, 20, 25], "\u306a\u304b\u3063": [2, 5, 6], "\u306a\u304c\u3089": 6, "\u306a\u304f": 2, "\u306a\u3051\u308c": 8, "\u306a\u3055": [2, 5, 6], "\u306a\u3057": [1, 9], "\u306a\u3063": [2, 6, 21, 22, 25, 28], "\u306a\u3069": [1, 2, 4, 6, 7, 8, 9, 11, 14, 15, 19, 25, 27, 29], "\u306a\u307e\u3057": 2, "\u306a\u3082\u306e": 2, "\u306a\u3089": 2, "\u306a\u3089\u3070": 2, "\u306a\u308a": [2, 5, 6, 8, 9, 11, 14], "\u306a\u308b": [1, 2, 6, 11], "\u306b\u3042\u308a": [21, 22, 25, 26, 27, 28], "\u306b\u304a\u3051\u308b": 6, "\u306b\u304a\u5bc4\u305b\u304f": 7, "\u306b\u305d\u306e": 25, "\u306b\u3064\u3044\u3066": [0, 1, 2, 4, 7, 8, 14, 16, 19, 21, 22, 23, 25, 26, 27, 28], "\u306b\u307e\u3068\u3081": 2, "\u306b\u3088\u3063": [5, 6], "\u306b\u3088\u3063\u3066": 8, "\u306b\u3088\u308a": 15, "\u306b\u3088\u308b": [2, 5, 13, 14, 15, 21, 23, 26, 29], "\u306b\u5bfe\u3057": [1, 9, 11, 14, 15, 20], "\u306b\u5bfe\u3059\u308b": 6, "\u306b\u5bfe\u5fdc": [1, 2, 4, 6, 15], "\u306b\u5f93\u3044": 6, "\u306b\u5f93\u3046": [2, 6], "\u306b\u5f93\u3063": 2, "\u306b\u95a2\u3059\u308b": [5, 7, 8, 14, 16, 21, 27], "\u306e\u3042\u3068": 8, "\u306e\u305a\u308c": 15, "\u306e\u3067": [1, 2, 5, 6, 25, 27, 29], "\u306e\u3069\u3061\u3089": 14, "\u306e\u307f": [1, 11, 16, 25], "\u306e\u3082": 6, "\u306e\u3088\u3046": [1, 6], "\u306f\u3058\u3081": 13, "\u306f\u3059\u3067": 10, "\u306f\u3059\u3079\u3066": 5, "\u306f\u305d\u308c\u305e\u308c": [21, 22, 25, 26, 27, 28], "\u3072\u3044\u3066": 1, "\u3072\u3068\u3064": [2, 6], "\u3078\u306e": [6, 14], "\u3079\u304d": 2, "\u307b\u3068\u3093\u3069": 2, "\u307e\u3057": [0, 15, 21, 26, 27], "\u307e\u3059": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29], "\u307e\u305a": [1, 29], "\u307e\u305b": [1, 2, 6, 8, 14, 20], "\u307e\u305f": [0, 1, 2, 4, 6, 8, 14, 21, 23, 27], "\u307e\u3067": [1, 2, 6, 14, 15], "\u307e\u3068\u3081": 6, "\u307e\u307e": [1, 2, 8, 9, 14], "\u307f\u306a\u3055": [14, 20], "\u307f\u307e\u3057\u3087": 29, "\u3082\u3057\u304f": 20, "\u3082\u3068": 15, "\u3082\u306e": [1, 2, 5, 6, 9, 10], "\u3084\u3059\u3044": 2, "\u3088\u3046": [1, 2, 6, 8, 11, 12, 21, 26, 29], "\u3088\u3073": 1, "\u3088\u308a": [1, 2, 22, 25, 28], "\u3089\u308c": [1, 2, 6, 10, 14, 15, 21, 23, 26, 27], "\u3089\u308c\u308b": [1, 2, 9, 25], "\u308c\u305a": [2, 5, 6], "\u308c\u307e\u305b": [2, 6], "\u308c\u308b": [2, 5, 9, 11, 14, 20, 24, 25], "\u308f\u304b\u308a": 21, "\u3092\u3054": 5, "\u3092\u3059\u3079": 6, "\u3092\u3064\u306a\u3052\u308b": 9, "\u3092\u3088\u304f": 1, "\u30a2\u30d5\u30a3\u30f3": [9, 14], "\u30a2\u30eb\u30b4\u30ea\u30b9\u30e0": [21, 22, 26, 27, 28], "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0": [5, 8, 9, 13, 14, 15, 16, 17, 19, 21, 22, 23, 24, 25, 26, 27, 28, 29], "\u30a2\u30f3\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": 13, "\u30a4\u30f3\u30b9\u30bf\u30f3\u30b9": [8, 9, 11], "\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": [1, 2, 4, 5, 6, 7, 13, 20, 21], "\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb\u30da\u30fc\u30b8": 29, "\u30a4\u30f3\u30bf\u30fc\u30d0\u30eb": 1, "\u30a4\u30f3\u30c7\u30c3\u30af\u30b9": [1, 2, 4, 6, 11, 22], "\u30a8\u30eb\u30b4\u30fc\u30c9": 2, "\u30aa\u30d6\u30b8\u30a7\u30af\u30c8": 9, "\u30aa\u30d7\u30b7\u30e7\u30f3": [19, 20, 22, 25, 28], "\u30aa\u30d7\u30b7\u30e7\u30f3\u30d1\u30e9\u30e1\u30fc\u30bf": 9, "\u30aa\u30da\u30ec\u30fc\u30c6\u30a3\u30f3\u30b0\u30b7\u30b9\u30c6\u30e0": 7, "\u30ab\u30e9\u30fc\u30de\u30c3\u30d7": 26, "\u30ab\u30ec\u30f3\u30c8\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": [9, 11], "\u30ab\u30fc\u30cd\u30eb": 1, "\u30ac\u30a4\u30c9\u30e9\u30a4\u30f3": 7, "\u30ac\u30a6\u30b7\u30a2\u30f3\u30d7\u30ed\u30bb\u30b9": 1, "\u30ac\u30a6\u30b9": [1, 2, 6, 22, 25, 28], "\u30ad\u30fc": [2, 6, 9], "\u30af\u30e9\u30b9": [9, 11, 12, 29], "\u30af\u30e9\u30b9\u30e1\u30bd\u30c3\u30c9": [8, 9, 12], "\u30b0\u30ea\u30c3\u30c9": [1, 2, 3, 6, 11, 13, 14, 15, 19, 21, 23], "\u30b0\u30ea\u30c3\u30c9\u30a4\u30f3\u30c7\u30c3\u30af\u30b9": 21, "\u30b3\u30a2": [22, 25, 28], "\u30b3\u30de\u30f3\u30c9": [1, 2, 4, 6, 19, 22, 25, 28], "\u30b3\u30e1\u30f3\u30c8": [4, 12], "\u30b3\u30f3\u30b9\u30c8\u30e9\u30af\u30bf": [1, 2, 4, 6, 8, 9, 11, 12, 29], "\u30b3\u30f3\u30bf\u30af\u30c8": 7, "\u30b3\u30f3\u30d1\u30a4\u30e9": 7, "\u30b3\u30fc\u30c9": [6, 9, 29], "\u30b5\u30d6\u30bb\u30af\u30b7\u30e7\u30f3": [2, 5, 6, 14, 22, 25], "\u30b5\u30d6\u30d5\u30a9\u30eb\u30c0": 16, "\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": [2, 6, 22], "\u30b5\u30f3\u30d7\u30eb": [1, 2, 4, 6, 22, 25, 28], "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a1\u30a4\u30eb": 19, "\u30b7\u30f3\u30dc\u30eb": [27, 28], "\u30b9\u30af\u30ea\u30d7\u30c8": [21, 22, 25, 26, 27, 28], "\u30b9\u30b1\u30fc\u30eb": 20, "\u30b9\u30b3\u30a2": [1, 21], "\u30b9\u30bf\u30fc\u30c8": 27, "\u30b9\u30c6\u30c3\u30d7": [1, 2, 11, 21, 22, 25, 27, 28], "\u30b9\u30c6\u30c3\u30d7\u30ab\u30a6\u30f3\u30c8": [1, 2], "\u30bb\u30af\u30b7\u30e7\u30f3": [8, 9, 13, 16, 17, 21, 22, 23, 25, 26, 27, 28, 29], "\u30bc\u30ed\u30d9\u30af\u30c8\u30eb": 14, "\u30bd\u30d5\u30c8\u30a6\u30a7\u30a2": [0, 10, 15, 19, 25, 28], "\u30bd\u30eb\u30d0\u30fc": [0, 2, 5, 6, 9, 11, 13, 14, 15, 16, 19, 23, 24, 25, 27], "\u30bd\u30fc\u30b9\u30b3\u30fc\u30c9": [15, 19, 29], "\u30bf\u30a4\u30df\u30f3\u30b0": [1, 2, 4, 6], "\u30c0\u30a6\u30f3\u30ed\u30fc\u30c9": [13, 21, 22, 25, 26, 27, 28, 29], "\u30c1\u30a7\u30c3\u30af\u30dd\u30a4\u30f3\u30c8": [1, 2, 4, 6, 8, 14], "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb": [0, 13, 21, 22, 25, 26, 27, 28], "\u30c4\u30fc\u30eb": [2, 6, 13, 25, 27], "\u30c6\u30ad\u30b9\u30c8\u30d5\u30a1\u30a4\u30eb": 4, "\u30c6\u30b9\u30c8": [14, 29], "\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": [8, 9, 11, 14, 20, 21, 22, 25, 26, 27, 28], "\u30c7\u30d0\u30c3\u30b0": 20, "\u30c7\u30d5\u30a9\u30eb\u30c8": [1, 2, 4, 6, 8, 9, 14, 21, 25, 26, 27], "\u30c7\u30fc\u30bf": [1, 2, 4, 6, 11, 15, 19, 22, 25], "\u30c7\u30fc\u30bf\u30bb\u30c3\u30c8": 1, "\u30c7\u30fc\u30bf\u30d5\u30a1\u30a4\u30eb": 11, "\u30c8\u30d4\u30c3\u30af": 7, "\u30c8\u30e9\u30c3\u30d7": [2, 5], "\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8": 5, "\u30cf\u30a4\u30d1\u30fc\u30d1\u30e9\u30e1\u30fc\u30bf": [1, 2, 5, 21, 22, 25, 28], "\u30d0\u30b0": 7, "\u30d0\u30e9\u30f3\u30b9": 1, "\u30d0\u30fc": 20, "\u30d0\u30fc\u30b8\u30e7\u30f3": [7, 13, 19], "\u30d1\u30b9": [1, 4, 9, 14], "\u30d1\u30c3\u30b1\u30fc\u30b8": [13, 20, 21, 27], "\u30d1\u30e9\u30e1\u30fc\u30bf": [3, 8, 9, 11, 12, 14, 15, 16, 18, 21, 22, 23, 25, 26, 27, 28, 29], "\u30d2\u30b9\u30c8\u30b0\u30e9\u30e0": 25, "\u30d3\u30fc\u30e0": 15, "\u30d5\u30a1\u30a4\u30eb": [7, 8, 9, 11, 12, 13, 20, 29], "\u30d5\u30a1\u30a4\u30eb\u30d1\u30b9": [2, 6], "\u30d5\u30a3\u30fc\u30eb\u30c9": 11, "\u30d5\u30a9\u30eb\u30c0": [21, 22, 25, 26, 27, 28], "\u30d5\u30ec\u30fc\u30e0\u30ef\u30fc\u30af": 15, "\u30d5\u30ed\u30fc": 12, "\u30d7\u30e9\u30c3\u30c8\u30d5\u30a9\u30fc\u30e0": 15, "\u30d7\u30ed\u30b0\u30e9\u30e0": [1, 2, 9, 11, 12, 14, 19, 26, 27], "\u30d7\u30ed\u30b0\u30e9\u30e0\u30d1\u30c3\u30b1\u30fc\u30b8": 15, "\u30d7\u30ed\u30b8\u30a7\u30af\u30c8": [0, 15], "\u30d7\u30ed\u30bb\u30b9": [2, 4, 6, 8, 11, 14, 22, 25, 26, 28], "\u30d7\u30ed\u30c3\u30c8": [21, 26, 27], "\u30d8\u30c3\u30c0\u30fc": 5, "\u30d8\u30eb\u30d1\u30fc\u30af\u30e9\u30b9": 8, "\u30d9\u30a4\u30ba": [3, 13, 14, 15, 19, 23], "\u30d9\u30af\u30c8\u30eb": [9, 11, 14, 25], "\u30d9\u30f3\u30c1\u30de\u30fc\u30af": 17, "\u30db\u30fc\u30e0\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": 9, "\u30dc\u30eb\u30c4\u30de\u30f3": [2, 6], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0": [13, 23], "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": [3, 13, 14, 15], "\u30de\u30c3\u30d4\u30f3\u30b0": 9, "\u30de\u30cb\u30e5\u30a2\u30eb": 25, "\u30e1\u30a4\u30f3\u30d7\u30ed\u30b0\u30e9\u30e0": [21, 22, 25, 26, 27, 28], "\u30e1\u30bd\u30c3\u30c9": [8, 9, 11], "\u30e1\u30c3\u30b7\u30e5": [8, 20, 26], "\u30e1\u30c3\u30b7\u30e5\u30c7\u30fc\u30bf": [1, 4, 8], "\u30e1\u30c3\u30b7\u30e5\u30d5\u30a1\u30a4\u30eb": [1, 4], "\u30e1\u30f3\u30d0\u30fc": 15, "\u30e2\u30b8\u30e5\u30fc\u30eb": [14, 15, 19], "\u30e2\u30c7\u30eb": 1, "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": [3, 6, 13, 14, 15, 20, 23, 28], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": [2, 6], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u30b7\u30df\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3": 2, "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u30b9\u30c6\u30c3\u30d7": [22, 25, 28], "\u30e2\u30fc\u30c9": [1, 2, 4, 6, 8], "\u30e6\u30fc\u30af\u30ea\u30c3\u30c9": 20, "\u30e6\u30fc\u30b6": [12, 29], "\u30e6\u30fc\u30b6\u30fc": [13, 15, 19], "\u30e9\u30a4\u30bb\u30f3\u30b9": 13, "\u30e9\u30a4\u30d6\u30e9\u30ea": 1, "\u30e9\u30f3\u30af": [8, 11, 16, 21, 22, 25, 26, 28], "\u30e9\u30f3\u30af\u30d5\u30a9\u30eb\u30c0": 22, "\u30e9\u30f3\u30c0\u30e0": [2, 5, 6, 14], "\u30e9\u30f3\u30c0\u30e0\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": [1, 21], "\u30ea\u30b5\u30f3\u30d7\u30ea\u30f3\u30b0": 6, "\u30ea\u30b9\u30c8": [1, 4, 5, 14, 20, 21], "\u30ea\u30bb\u30c3\u30c8": 6, "\u30ea\u30d5\u30a1\u30ec\u30f3\u30b9": 29, "\u30eb\u30fc\u30c8\u30c7\u30a3\u30ec\u30af\u30c8\u30ea": [8, 9, 11], "\u30eb\u30fc\u30d7": 20, "\u30ec\u30d3\u30e5\u30fc": 15, "\u30ec\u30d5\u30a1\u30ec\u30f3\u30b9": [22, 28], "\u30ec\u30d7\u30ea\u30ab": [6, 13, 14, 15, 23, 28], "\u30ed\u30b0": [14, 16, 27], "\u30ed\u30b0\u30d5\u30a1\u30a4\u30eb": 14, "\u30ed\u30fc\u30ab\u30eb": 19, "\u30fb\u30b9\u30ec\u30c3\u30c9": 11, "\u30fb\u6700\u5927\u5024": 8, "\u4e00\u3064": 27, "\u4e00\u5b9a": 2, "\u4e00\u5f0f": 15, "\u4e00\u6176": 15, "\u4e00\u62ec": [21, 22, 25, 26, 27, 28], "\u4e00\u65b9": [2, 14], "\u4e00\u69d8": [2, 5, 6], "\u4e00\u756a": [2, 21, 29], "\u4e00\u756a\u4e0a": 14, "\u4e00\u81f4": [1, 2, 4, 5, 6], "\u4e00\u81f4\u3057": 1, "\u4e00\u822c": 2, "\u4e00\u90e8": [0, 25], "\u4e0a\u304c\u308b": 2, "\u4e0a\u3052\u308b": 2, "\u4e0a\u4e0b": 2, "\u4e0a\u56de\u308b": [2, 5, 6], "\u4e0a\u8a18": [21, 26, 27], "\u4e0a\u9650": [22, 25, 28], "\u4e0b\u304c\u308a": 6, "\u4e0b\u3052": [2, 6, 28], "\u4e0b\u3052\u308b": [2, 6, 22], "\u4e0b\u308b": 2, "\u4e0b\u56de\u308b": [2, 5, 6], "\u4e0b\u8a18": 19, "\u4e0b\u9650": [22, 25, 28], "\u4e0d\u53ef\u80fd": 2, "\u4e0d\u7b49": 9, "\u4e0e\u3048": [9, 15, 21, 23], "\u4e0e\u3048\u308b": [1, 9, 14, 21, 22, 24, 25, 27, 28], "\u4e21\u8005": 1, "\u4e21\u8fba": 2, "\u4e26\u3079": [14, 20], "\u4e26\u5217": [1, 2, 4, 6, 11, 22, 25, 26, 28], "\u4e26\u5217\u6570": [1, 2, 4, 6], "\u4e26\u9032": 14, "\u4e2d\u5fc3": 2, "\u4e2d\u65ad": [1, 2, 4, 6, 8, 14], "\u4e2d\u8eab": 25, "\u4e2d\u9593": 11, "\u4e57\u308a": 2, "\u4e71\u6570": [8, 14, 21, 25, 27], "\u4e88\u5b9a": 15, "\u4e8b\u524d": 21, "\u4e8b\u5f8c": 25, "\u4e8b\u67c4": 9, "\u4e8b\u9805": [10, 13], "\u4e8c\u6b21": 17, "\u4ea4\u63db": [3, 13, 14, 15, 23], "\u4eca\u56de": [21, 25, 26], "\u4eca\u5f8c": 15, "\u4ed8\u304d": 6, "\u4ed8\u3051": 14, "\u4ed8\u8fd1": [22, 28], "\u4ee3\u5165": 2, "\u4ee3\u5206": 14, "\u4ee5\u4e0a": [2, 19], "\u4ee5\u4e0b": [1, 2, 4, 5, 6, 7, 8, 11, 14, 15, 16, 17, 19, 20, 21, 22, 23, 25, 26, 27, 28, 29], "\u4ee5\u964d": [1, 2, 4, 6], "\u4eee\u5b9a": [9, 21, 22, 25, 26, 27, 28], "\u4efb\u610f": 14, "\u4f4d\u7f6e": 15, "\u4f4e\u901f": [15, 19], "\u4f4e\u901f\u96fb\u5b50\u7dda": 14, "\u4f55\u56de": 5, "\u4f5c\u308b": 5, "\u4f5c\u6210": [1, 4, 8, 9, 12, 21, 22, 25, 26, 27, 28], "\u4f5c\u696d": [8, 11], "\u4f7f\u3046": [5, 6, 9, 14, 29], "\u4f7f\u3048\u308b": [22, 25, 28], "\u4f7f\u308f": [5, 9, 24], "\u4f7f\u7528": [2, 6, 7, 10, 11, 20, 21, 22, 23, 25, 26, 27, 28], "\u4f8b\u3048": [6, 14, 27], "\u4f8b\u3068\u3057\u3066": [23, 29], "\u4f9d\u308a": 16, "\u4fca\u592b": 15, "\u4fdd\u5b58": [8, 11, 14], "\u4fdd\u6301": 22, "\u500b\u6570": [14, 21, 25, 26, 27, 28], "\u5019\u88dc": [1, 2, 4, 8, 21, 26, 27], "\u5019\u88dc\u70b9": 1, "\u501f\u308a": 0, "\u5024\u3068": 5, "\u5024\u63a2": [5, 14, 27], "\u504f\u308b": 2, "\u504f\u5dee": [2, 6, 22, 25, 28], "\u5065\u592b": 15, "\u5143\u5316": 5, "\u5143\u7269": [14, 15], "\u5148\u982d": 9, "\u5165\u308a": 1, "\u5165\u308b": 1, "\u5165\u308c": 2, "\u5165\u51fa": 14, "\u5165\u51fa\u529b": 8, "\u5165\u529b": [7, 8, 9, 11, 12, 13, 16, 29], "\u5168\u3066": 26, "\u5168\u4f53": [2, 9, 10, 14, 20, 25, 27], "\u5168\u53cd": [15, 19], "\u5168\u63a2": 23, "\u516c\u5f0f": 5, "\u5171\u901a": [8, 10, 13], "\u5175\u982d": 15, "\u5177\u4f53": [9, 14, 22, 26, 27, 28], "\u5185\u5bb9": [8, 16], "\u5185\u90e8": [25, 26, 27], "\u518d\u5b9f\u884c": 8, "\u518d\u73fe": 1, "\u518d\u8a13": 1, "\u518d\u958b": [1, 2, 4, 6, 14, 16], "\u5192\u982d": 25, "\u5199\u50cf": [9, 14], "\u51b7\u5374": 2, "\u51e6\u7406": 8, "\u51fa\u529b": [7, 8, 9, 11, 13, 14, 20, 21, 22, 25, 26, 27], "\u51fa\u6765": 14, "\u51fa\u73fe": [2, 5, 6], "\u5206\u304b\u308a": [22, 27], "\u5206\u5272": [1, 2, 6, 8], "\u5206\u5c90": 29, "\u5206\u5e03": [2, 6, 22, 25, 28], "\u5206\u6563": 6, "\u5206\u914d": [6, 28], "\u5217\u3081": 22, "\u5217\u578b": 8, "\u5217\u6319": [2, 6], "\u5217\u6570": 14, "\u5217\u76ee": [1, 2, 4, 6, 16, 21, 22, 25, 26, 28], "\u5217\u8a08": 2, "\u521d\u3081": 1, "\u521d\u671f": 5, "\u521d\u671f\u5024": [2, 5, 6, 8, 14, 21, 27], "\u521d\u671f\u5316": [2, 5, 6, 8, 9, 14], "\u5224\u5b9a": [5, 27], "\u5225\u9014": 19, "\u5229\u7528": [1, 2, 6, 11, 12, 14, 19, 20, 21, 25, 27, 29], "\u5230\u9054": 27, "\u5236\u7d04": [2, 8, 9, 14, 23, 25], "\u5236\u9650": 23, "\u524d\u51e6": [8, 16], "\u524d\u56de": 16, "\u524d\u8005": 1, "\u5272\u3057": 4, "\u5272\u308a": 4, "\u5272\u308a\u5f53\u3066\u308b": [2, 6], "\u5272\u308b": 5, "\u5272\u5f53": 6, "\u5272\u611b": 25, "\u52a0\u3048": 14, "\u52a0\u71b1": 2, "\u52d5\u304b": 2, "\u52d5\u304b\u3059": [2, 5], "\u52d5\u304d": 2, "\u52d5\u4f5c": [1, 2, 4, 6, 8], "\u5316\u4e2d": 5, "\u5316\u5229": 19, "\u5316\u53ef": 2, "\u5316\u554f": [3, 13, 21, 22, 23, 26, 28], "\u5316\u56e0\u5b50": 6, "\u5316\u7d50": 8, "\u5316\u904e": 1, "\u533a\u5207\u3063": 14, "\u533a\u5207\u308a": [14, 20], "\u5341\u5206": [1, 14], "\u5358\u4f4d": [5, 8, 14], "\u539f\u5b50": 15, "\u53c2\u7167": [1, 2, 5, 6, 8, 9, 11, 14, 16, 19, 21, 22, 25, 26, 27, 28, 29], "\u53c2\u7167\u304f": 5, "\u53c2\u8003": 0, "\u53cd\u5c04": 14, "\u53cd\u5fa9": 5, "\u53ce\u675f": [2, 5, 27], "\u53d6\u308a": [8, 9, 11], "\u53d6\u308a\u3046\u308b": [1, 2, 4, 5, 6], "\u53d6\u308a\u4e0a\u3052": 24, "\u53d6\u308b": [2, 14], "\u53d6\u5f97": [8, 11], "\u53d7\u3051": [0, 2, 8, 11, 14, 15, 22, 28], "\u53d7\u3051\u4ed8\u3051": 7, "\u53d7\u3051\u5165\u308c": 2, "\u53d7\u3051\u53d6\u308a": 11, "\u53ef\u80fd": [1, 2, 12, 14, 15, 19, 20, 25, 27, 29], "\u53ef\u8996\u5316": 25, "\u53f3\u56f3": [21, 28], "\u5404mpi": 14, "\u5404\u65b9": [21, 26], "\u5404\u6b21": [1, 4], "\u5404\u6b21\u5143": 5, "\u5404\u6e29": [2, 28], "\u5404\u70b9": [1, 2, 5, 6], "\u5404\u7a2e": [14, 16], "\u5408\u308f": 13, "\u5408\u308f\u305b": 5, "\u5409\u898b": 15, "\u540c\u3058": [1, 2, 4, 6, 21, 22, 25, 26, 28], "\u540c\u6642": [6, 14, 19], "\u540c\u6642\u306b": 26, "\u540c\u68b1": 19, "\u540c\u69d8": [2, 14, 20, 22, 26, 28], "\u540d\u524d": [8, 14, 20, 21, 22, 25, 26, 27, 28], "\u540d\u79f0": 15, "\u5411\u3044": 2, "\u5411\u3051": [13, 19], "\u5411\u4e0a": 1, "\u5426\u304b": [2, 6], "\u542b\u307e": 24, "\u542b\u307e\u308c\u308b": [25, 27], "\u542b\u3081": 20, "\u5468\u671f": 6, "\u5468\u8fba": 6, "\u547c\u3070": 2, "\u547c\u3073": 6, "\u547c\u3073\u51fa\u3055": 11, "\u547c\u3073\u51fa\u3057": [8, 11, 14, 16, 27], "\u547c\u3093": 8, "\u547d\u540d": 0, "\u554f\u3044\u5408\u308f\u305b": 7, "\u554f\u3044\u5408\u308f\u305b\u308b": 7, "\u554f\u984c": [2, 5, 7, 11, 12, 13, 14, 15, 16, 19, 23, 24, 27], "\u56de\u308b": 2, "\u56de\u547c": 14, "\u56de\u6298": [14, 15, 19], "\u56de\u6570": [1, 2, 5, 6, 14, 21, 22, 25, 28], "\u56de\u7b54": 25, "\u56e0\u5b50": [2, 6], "\u56f0\u96e3": 6, "\u56f3\u793a": [22, 25, 26, 28], "\u56fa\u4f53": 15, "\u56fa\u5b9a": [2, 6], "\u56fa\u6709": 11, "\u5730\u70b9": 2, "\u578b\u63a2": [3, 13, 15, 23], "\u57fa\u3065\u3044": 2, "\u57fa\u5e95": [1, 8, 11], "\u5831\u544a": 7, "\u5834\u5408": [1, 2, 4, 5, 6, 7, 8, 9, 11, 14, 16, 19, 20, 21, 22, 25, 26, 27, 28, 29], "\u5834\u6240": 1, "\u585a\u672c": 0, "\u5897\u3084": [1, 2, 28], "\u5909\u3048": 5, "\u5909\u3048\u308b": 22, "\u5909\u308f\u308a": 8, "\u5909\u5316": [2, 6, 22, 25, 28], "\u5909\u63db": [9, 14], "\u5909\u6570": [0, 1, 4, 5, 8, 9, 11, 14, 21, 25, 27], "\u5909\u66f4": [6, 7], "\u5916\u90e8": 11, "\u591a\u3044": [22, 25, 28], "\u591a\u304f": [1, 15], "\u5927\u304d": [1, 14], "\u5927\u304d\u304f": 6, "\u5927\u304d\u306a": 14, "\u5927\u5b66": [0, 15], "\u5927\u5b66\u9662": 15, "\u5927\u898f": 2, "\u5931\u6557": 8, "\u59cb\u307e\u308b": 4, "\u59cb\u70b9": [2, 6], "\u5b58\u5728": [2, 6, 8], "\u5b66\u7fd2": 1, "\u5b8c\u5168": 1, "\u5b9a\u3081": [1, 2, 6], "\u5b9a\u3081\u308c": 2, "\u5b9a\u671f": 14, "\u5b9a\u7fa9": [5, 9, 12, 13, 14, 15, 19, 20, 23, 25, 29], "\u5b9a\u7fa9\u6e08": [17, 19], "\u5b9f\u6570": [1, 2, 4, 5, 6, 14], "\u5b9f\u73fe": 2, "\u5b9f\u884c": [1, 2, 4, 6, 7, 8, 9, 10, 11, 13, 14, 16, 20, 23, 29], "\u5b9f\u88c5": [1, 15, 22], "\u5b9f\u969b": [2, 6, 9, 14, 22, 25, 28], "\u5b9f\u9a13": [15, 19], "\u5bb9\u6613": 2, "\u5bc4\u4e0e": 1, "\u5bc6\u5ea6": 6, "\u5bfe\u5fdc": [1, 2, 4, 5, 6, 8, 11, 12, 26, 28], "\u5bfe\u6570": [2, 6, 22, 25, 28], "\u5bfe\u79f0": 2, "\u5c04\u9ad8": [15, 19], "\u5c0e\u5165": 2, "\u5c0f\u3055\u3044": [2, 22, 26, 28], "\u5c0f\u3055\u304f": 28, "\u5c0f\u5024": 5, "\u5c11\u3057": 2, "\u5c11\u306a\u3044": 1, "\u5c11\u306a\u304f": [8, 14], "\u5c40\u6240": [2, 5], "\u5c55\u958b": 9, "\u5c65\u6b74": [13, 21], "\u5ca9\u672c": 15, "\u5de1\u76ee": 11, "\u5de5\u5b66": 15, "\u5de6\u56f3": [21, 28], "\u5dee\u5206": [5, 25], "\u5e30\u7740": 2, "\u5e73\u5747": 6, "\u5e73\u884c": 14, "\u5e74\u5ea6": [0, 15], "\u5e83\u304f": 22, "\u5e83\u3052": 10, "\u5ea6\u70b9": 2, "\u5ea7\u6a19": [1, 2, 4, 5, 6, 20, 25], "\u5f0f\u5236": 9, "\u5f0f\u6570": 14, "\u5f0f\u6a5f": 25, "\u5f15\u304d\u7d99": [1, 2], "\u5f15\u6570": [1, 2, 4, 6, 8, 9, 11, 20], "\u5f15\u7528": [15, 20], "\u5f37\u3044": 2, "\u5f37\u529b": 1, "\u5f37\u5ea6": 14, "\u5f62\u5f0f": [1, 2, 4, 5, 6, 8, 9, 12, 14, 17, 27], "\u5f8c\u51e6": [8, 16], "\u5f8c\u8005": 1, "\u5f90\u3005": 2, "\u5f93\u3063": [6, 7], "\u5f97\u3089\u308c": [5, 27], "\u5f97\u308b": 8, "\u5fc5\u305a": 11, "\u5fc5\u8981": [1, 2, 4, 5, 6, 8, 11, 13, 14, 20, 29], "\u5fc5\u9808": 1, "\u5fdc\u3058": 5, "\u6027\u80fd": [17, 24], "\u606d\u5e73": 0, "\u60c5\u5831": [1, 5, 6, 7, 8, 9, 16, 22, 25, 28], "\u610f\u5473": [1, 4], "\u611f\u8b1d": 0, "\u6210\u5206": 5, "\u623b\u308a": 8, "\u623b\u308b": 8, "\u624b\u6cd5": [1, 2, 6, 23], "\u624b\u9806": [22, 26, 27, 28], "\u6271\u3044": [2, 11], "\u6271\u3046": 9, "\u6298\u6cd5": 15, "\u62c5\u5f53": [2, 6], "\u62e1\u5f35": 6, "\u6301\u3061": [2, 5, 6, 9, 14, 24], "\u6301\u3064": [9, 11, 21, 22, 28], "\u6307\u5b9a": [1, 2, 4, 6, 7, 8, 9, 14, 17, 20, 21, 22, 25, 26, 27, 28, 29], "\u6307\u793a": 8, "\u632f\u308b": 4, "\u633f\u5165": 29, "\u6368\u3066": 25, "\u63a1\u629e": [2, 6, 22, 25, 28], "\u63a1\u7528": 14, "\u63a2\u3059": [2, 15], "\u63a2\u7d22": [1, 2, 4, 5, 6, 8, 9, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 26, 27, 29], "\u63a8\u5968": 19, "\u63a8\u5b9a": [15, 21, 22, 26, 27, 28], "\u63b2\u8f09": 25, "\u63d0\u4f9b": [2, 6, 8, 19], "\u63d0\u6848": [1, 2, 6], "\u63f4\u7528": 1, "\u640d\u5931": 15, "\u64ec\u4f3c": [6, 8, 14, 25], "\u652f\u63f4": [0, 15], "\u6539\u884c": 14, "\u6539\u9020": [19, 29], "\u6570\u5024": 6, "\u6570\u591a\u304f": 2, "\u6570\u79d2": [21, 22, 26, 27, 28], "\u6574\u5099": 15, "\u6574\u5217": 22, "\u6574\u6570": [1, 2, 4, 5, 6, 14, 16], "\u6587\u5b57": 8, "\u6587\u5b57\u5217": 14, "\u6587\u732e": 15, "\u65b9\u5411": 2, "\u65b9\u6cd5": [0, 2, 6, 9, 10, 13, 14, 21, 22, 23, 25, 26, 27, 28, 29], "\u65e9\u304f": 1, "\u65e9\u671f": 7, "\u6642\u3068": [22, 28], "\u6642\u70b9": [6, 21], "\u6642\u78ba": 6, "\u6642\u7cfb": 2, "\u6642\u9593": [1, 2, 4, 6, 8, 14, 16, 21, 22, 25, 26, 27, 28], "\u666e\u901a": 6, "\u6674\u9053": 15, "\u66f4\u65b0": [1, 2, 6, 14, 19, 22, 25, 28], "\u66f8\u304d\u51fa\u3055": [14, 26], "\u66f8\u304d\u51fa\u3057": [8, 14], "\u66f8\u304d\u51fa\u3059": [8, 11, 14], "\u66f8\u304d\u8fbc\u307e": [22, 25, 28], "\u66f8\u304f": 6, "\u66f8\u5f0f": [2, 6, 22, 25, 28], "\u6700\u3082": 1, "\u6700\u3082\u65b0\u3057\u3044": [1, 2, 4, 6], "\u6700\u521d": [1, 5, 8, 21, 22, 25, 26, 27, 28], "\u6700\u5927": [1, 2, 4, 5, 6, 21, 22, 25, 26, 27, 28], "\u6700\u5927\u5024": [2, 6], "\u6700\u5c0f": [1, 2, 3, 4, 5, 6, 8, 13, 14, 15, 21, 22, 23, 25, 26, 27, 28], "\u6700\u5c0f\u5024": [2, 4, 6, 22, 24, 25, 27, 28, 29], "\u6700\u5f8c": [4, 5, 6, 23, 25, 28], "\u6700\u7d42": 5, "\u6700\u7d42\u7684": [21, 26, 27], "\u6700\u9069": [2, 3, 5, 8, 10, 12, 13, 14, 15, 18, 19, 23, 24, 25, 29], "\u6700\u9069\u5024": 17, "\u6700\u9069\u5316": 8, "\u6700\u9069\u89e3": [1, 2], "\u6700\u9ad8": 21, "\u6709\u52b9": [1, 2, 4, 6, 8, 14], "\u6709\u76ca": 1, "\u6709\u9650": 2, "\u671f\u5316": [1, 2, 4, 6], "\u671f\u5f85": [1, 6, 28], "\u671f\u6027": 2, "\u671f\u9593": 25, "\u672c\u5c71": 15, "\u672c\u7ae0": 10, "\u6761\u4ef6": [1, 2, 4, 6, 8, 9, 14], "\u6771\u4eac": [0, 15], "\u6790\u5411": [14, 15], "\u6838\u878d\u5408": 15, "\u683c\u7d0d": [21, 22, 25, 26, 27, 28], "\u6975\u5c0f": [22, 24], "\u69cb\u3044": 6, "\u69cb\u6210": 14, "\u69cb\u9020": [15, 19], "\u69d8\u3005": 22, "\u6a19\u6e96": [6, 15, 21, 26, 28], "\u6a21\u4e26": 2, "\u6a2a\u8ef8": [25, 28], "\u6a4b\u6e21": 14, "\u6a5f\u68b0": 1, "\u6a5f\u80fd": [1, 2, 4, 6, 8, 14], "\u6b21\u5143": [4, 5, 8, 9, 11, 14, 19, 20, 22, 25, 26, 28], "\u6b63\u3057\u3044": 21, "\u6b63\u3057\u304f": 25, "\u6b63\u78ba": 2, "\u6b63\u898f": 5, "\u6b63\u89e3": 1, "\u6b8b\u308a": 6, "\u6b8b\u5ff5": 6, "\u6bd4\u8f03": 25, "\u6c42\u3081": [1, 27], "\u6c42\u3081\u308b": [2, 5, 6], "\u6c4e\u7528": 15, "\u6c7a\u3081": 1, "\u6c7a\u3081\u308b": 2, "\u6c7a\u5b9a": [6, 14], "\u6cd5\u5229": 19, "\u6ce8\u610f": 2, "\u6d3b\u7528": 1, "\u6d41\u308c": 6, "\u6df1\u304f": 2, "\u6df1\u3055": 2, "\u6e08\u307f": [10, 12, 19], "\u6e21\u3055": 11, "\u6e21\u3057": [9, 12, 14, 20], "\u6e21\u305b": 29, "\u6e29\u5ea6": [2, 6, 22, 25, 28], "\u6e29\u5ea6\u70b9": 6, "\u6e80\u305f": [2, 6, 9, 25], "\u6e96\u3058": 15, "\u6e96\u5099": [19, 21, 22, 25, 26, 27, 28], "\u70b9\u4ed8": 22, "\u70b9\u5217": 6, "\u70b9\u5bfe": 20, "\u70b9\u6570": [1, 28], "\u7121\u3044": 1, "\u7121\u52b9": 8, "\u7121\u6b21": 5, "\u7121\u8996": 4, "\u7121\u9650": [2, 5, 6], "\u713c\u304d": 2, "\u713c\u623b": 2, "\u713c\u623b\u3057\u6cd5": 2, "\u7247\u65b9": [2, 6], "\u7269\u6027": [0, 15], "\u7269\u7406": 15, "\u7269\u8cea": 19, "\u7279\u306b": 2, "\u7279\u5b9a": 2, "\u72b6\u614b": [1, 2, 4, 6, 8, 14, 16], "\u72ec\u7acb": 19, "\u72ed\u307e\u308b": 2, "\u7387\u5206": 6, "\u73fe\u5728": [2, 9, 11, 14, 19, 25], "\u74b0\u5883": 13, "\u751f\u3058": 7, "\u751f\u307e": 2, "\u751f\u6210": [2, 6, 8, 14, 20, 25, 26, 28], "\u7528\u3044": [1, 2, 3, 4, 5, 6, 8, 9, 14, 20, 21, 22, 23, 25, 26, 27, 28, 29], "\u7528\u3044\u308b": [6, 9, 14, 17, 21, 22, 25, 26, 27, 28, 29], "\u7528\u610f": [2, 4, 8, 12, 14, 15, 19, 23, 25, 26, 27, 29], "\u7528\u6642": 19, "\u7531\u6765": 2, "\u756a\u53f7": [1, 2, 4, 6, 11, 12, 16, 22, 25, 28], "\u7591\u4f3c": 14, "\u767a\u5c55": 2, "\u767a\u751f": 8, "\u76ee\u4ee5\u964d": [1, 2, 4, 5, 6, 22, 25, 28], "\u76ee\u7684": [1, 2, 4, 5, 8, 9, 11, 17, 22, 25, 28], "\u76f4\u3057": [2, 22], "\u76f4\u4e0b": [21, 22, 25, 26, 27, 28], "\u76f4\u63a5": [2, 6, 19, 20], "\u76f4\u7dda": 25, "\u76f8\u5bfe": 9, "\u76f8\u5bfe\u30d1\u30b9": 9, "\u76f8\u5f53": 8, "\u76f8\u8ac7": 7, "\u7701\u7565": [9, 14, 21, 26, 27], "\u771f\u507d\u5024": [2, 6, 14], "\u77e5\u3089": 7, "\u7814\u7a76": [0, 7, 15], "\u7814\u7a76\u6240": 15, "\u78ba\u304b\u3081": 2, "\u78ba\u7387": [2, 6, 25], "\u78ba\u8a8d": [5, 9, 25], "\u793a\u3055": [2, 6], "\u793a\u3057": 25, "\u793a\u3059": 19, "\u7956\u5148": [6, 28], "\u79d1\u5b66": 15, "\u79d1\u7814": 0, "\u79fb\u52d5": [2, 6, 8, 14, 21, 22, 25, 26, 27, 28], "\u7a0b\u5ea6": [2, 21, 22, 25, 26, 27, 28], "\u7a2e\u3068\u3057\u3066": 14, "\u7a2e\u985e": [8, 14], "\u7a7a\u767d": [14, 20], "\u7a7a\u9593": [1, 2, 3, 4, 5, 6, 8, 14, 20, 22, 25, 26, 28], "\u7b49\u5206": [2, 4, 6, 22, 25, 28], "\u7b49\u9593": [1, 4], "\u7b49\u9ad8": [21, 26, 27], "\u7bc4\u56f2": [8, 10, 14, 21, 22, 23, 25, 26, 27, 28], "\u7c21\u5358": [2, 6, 22, 23, 28, 29], "\u7c21\u6613": 5, "\u7cbe\u5ea6": [1, 2], "\u7cfb\u7d71\u7684": 5, "\u7d04\u5f0f": [13, 23], "\u7d22\u6cd5": 15, "\u7d39\u4ecb": 25, "\u7d42\u308f\u3063": 6, "\u7d42\u308f\u308a": [21, 22, 25, 26, 27, 28], "\u7d42\u4e86": [1, 2, 4, 6, 8, 14], "\u7d42\u70b9": [2, 6], "\u7d44\u307f\u5408\u308f": 10, "\u7d44\u307f\u5408\u308f\u305b": [15, 19], "\u7d4c\u8def": 27, "\u7d4c\u904e": [1, 2, 4, 5, 6, 14, 16], "\u7d50\u5408": 28, "\u7d50\u679c": [1, 2, 3, 5, 8, 9, 11, 14], "\u7d71\u8a08": 28, "\u7d76\u5bfe\u30d1\u30b9": 9, "\u7d99\u627f": [8, 11], "\u7d99\u7d9a": [1, 2, 6, 8], "\u7d9a\u3051": 21, "\u7dcf\u56de": 6, "\u7dcf\u6570": 6, "\u7dda\u56de": [14, 15, 19], "\u7dda\u5f62": [1, 9, 14], "\u7de8\u96c6": 29, "\u7e26\u8ef8": [25, 28], "\u7e70\u308a": 2, "\u7e70\u308a\u8fd4\u3057": [1, 2, 5, 14], "\u7e70\u308a\u8fd4\u3057\u6bce": 27, "\u7f6e\u3044": [21, 22, 25, 26, 27, 28], "\u8003\u3048": [1, 6], "\u811a\u6ce8": 2, "\u8131\u51fa": 2, "\u81ea\u5206": [10, 20, 23], "\u81ea\u52d5": [4, 6, 8, 9], "\u81ea\u5df1": 20, "\u81ea\u660e": [4, 9], "\u81ea\u8eab": [15, 20], "\u826f\u3044": [1, 6, 21], "\u826f\u304b\u3063": 1, "\u826f\u304f\u884c\u3046": 1, "\u884c\u3044": [1, 2, 4, 5, 6, 8, 19, 21, 22, 25, 26, 27, 28], "\u884c\u3046": [1, 2, 4, 6, 19, 21, 22, 25, 26, 27, 28], "\u884c\u3048": 6, "\u884c\u3063": [2, 6, 22, 25, 26, 28], "\u884c\u308f": [1, 6, 14], "\u884c\u5217": [6, 9, 14, 25], "\u884c\u6570": 14, "\u884c\u76ee": 5, "\u8868\u3055": 24, "\u8868\u3057": [11, 14], "\u8868\u3059": [21, 25, 26, 27, 28], "\u8868\u5f0f": 24, "\u8868\u793a": 20, "\u8868\u9762": 15, "\u8868\u9762x": [14, 19], "\u88d5\u4e00": 15, "\u8907\u6570": [2, 6, 24], "\u8981\u6c42": [22, 25, 28], "\u8981\u7d20": [9, 14], "\u898b\u3048": 2, "\u898b\u3066": 22, "\u898b\u308b": [22, 25, 28], "\u898f\u5b9a": 14, "\u898f\u683c": 6, "\u89e3\u304d": [3, 10, 27], "\u89e3\u304f": 23, "\u89e3\u6790": [13, 14, 15, 19, 21, 22, 23, 25, 26, 27, 28, 29], "\u89e3\u6c7a": [2, 7], "\u89e3\u8aac": 10, "\u89e3\u91c8": 9, "\u8a08\u6e2c": 8, "\u8a08\u7b97": [1, 2, 4, 5, 6, 9, 14, 16, 17, 18, 20], "\u8a13\u7df4": 1, "\u8a18\u3057": [22, 25, 28], "\u8a18\u8f09": [1, 2, 4, 5, 6, 7, 16, 21, 26], "\u8a18\u8ff0": [8, 9, 11, 14, 21, 22, 26, 27, 28], "\u8a18\u9332": [14, 22, 28], "\u8a2d\u5b9a": [5, 8, 9, 11, 14, 21, 22, 25, 26, 27, 28, 29], "\u8a2d\u8a08": 0, "\u8a55\u4fa1": [1, 2, 4, 5, 6, 9, 14, 17, 21, 22, 24, 25, 26, 28], "\u8a66\u307f": [22, 25], "\u8a73\u3057\u3044": 25, "\u8a73\u3057\u304f": [5, 14, 19], "\u8a73\u7d30": [2, 5, 6, 8, 9, 14, 21, 22, 25, 26, 27, 28, 29], "\u8aa4\u5dee": [1, 6, 28], "\u8aac\u660e": [1, 2, 4, 5, 6, 9, 14, 17, 23], "\u8aad\u307f\u53d6\u3063": 11, "\u8aad\u307f\u53d6\u308a": 8, "\u8aad\u307f\u8fbc\u307e": 16, "\u8aad\u307f\u8fbc\u307f": [1, 4], "\u8aad\u307f\u8fbc\u3080": 12, "\u8aad\u307f\u8fbc\u3093": 8, "\u8ab2\u3055": 9, "\u8ab2\u3055\u305a": 14, "\u8ab2\u3057": 25, "\u8ab2\u3059": [2, 9, 14], "\u8abf\u3079": 2, "\u8abf\u3079\u308b": 2, "\u8b1d\u8f9e": 13, "\u8c37\u3068\u3057\u3066": 2, "\u8cea\u69cb": [14, 15], "\u8d77\u70b9": [9, 11, 14], "\u8d8a\u3048": 2, "\u8db3\u3057": 5, "\u8ddd\u96e2": 20, "\u8e0f\u307e\u3048\u308b": 2, "\u8ee2\u9001": 8, "\u8f9e\u66f8": [8, 9], "\u8fd1\u304f": 2, "\u8fd1\u4f3c": 1, "\u8fd1\u508d": 20, "\u8fd4\u3057": [1, 8, 9, 11], "\u8fd4\u3059": [2, 11], "\u8ffd\u52a0": [0, 1, 8, 11, 13, 22, 23, 25, 28], "\u9006\u554f": [9, 10, 23, 27], "\u9006\u554f\u984c": 23, "\u9006\u6e29": [2, 6, 28], "\u9006\u6e29\u5ea6": [2, 6], "\u9014\u4e2d": [1, 5], "\u901a\u3057": 16, "\u901a\u308a": [6, 27], "\u901a\u4f8b": 11, "\u901a\u5e38": [1, 21, 22, 25, 26, 27, 28], "\u901f\u967d": [15, 19], "\u9020\u89e3": [14, 15], "\u9023\u7d61": 7, "\u9023\u7d9a": [2, 6, 8, 22, 28], "\u9032\u6357": 20, "\u9032\u6357\u30d0\u30fc": 20, "\u904e\u53bb": 14, "\u904e\u7a0b": 1, "\u9069\u5f53": [1, 2, 6], "\u9069\u7528": [10, 13, 15, 23], "\u9077\u79fb": [2, 6], "\u9078\u3073": 2, "\u9078\u3076": 1, "\u9078\u3076\u304b": 1, "\u9078\u3079": 17, "\u9078\u629e": [1, 29], "\u90e8\u5206": 25, "\u914d\u4f4d": 6, "\u914d\u5206": 8, "\u914d\u5e03": [14, 15], "\u91cd\u307f": [2, 6, 28], "\u91cd\u8981": [1, 2, 5], "\u91cf\u5b50": 15, "\u91e3\u308a\u5408\u3044": [2, 6], "\u9577\u3055": [1, 2, 4, 5, 6, 20], "\u958b\u59cb": [6, 16, 28], "\u958b\u767a": [0, 13, 19], "\u9593\u9694": 2, "\u95a2\u6570": [1, 2, 4, 5, 6, 8, 9, 11, 13, 14, 15, 17, 21, 22, 23, 25, 26, 27, 28], "\u95a2\u9023": [2, 6, 7, 13], "\u9632\u3050": 2, "\u964d\u4e0b": 6, "\u9664\u3055": 20, "\u9664\u7b97": 20, "\u96a3\u63a5": 20, "\u96c6\u4e2d": [22, 28], "\u96c6\u5408": [1, 4, 8], "\u96c6\u7d04": 11, "\u96e2\u6563": [2, 6, 8, 20], "\u96fb\u5b50": [14, 15, 19], "\u9752\u5c71": 15, "\u9752\u8272": 27, "\u975e\u5468": 2, "\u975e\u5e38": 2, "\u9805\u76ee": 25, "\u9806\u554f": [9, 15, 19, 23, 29], "\u9806\u554f\u984c": [10, 15, 19], "\u9806\u756a": [4, 8], "\u9818\u57df": [8, 22], "\u983b\u5ea6": [2, 6, 27], "\u984c\u89e3": [9, 23, 27], "\u9ad8\u3044": 1, "\u9ad8\u5ea6": [0, 15], "\u9ad8\u6e29": 22, "\u9ad8\u901f": [14, 20], "\u9ce5\u53d6": 15, "\u9ed2\u7dda": 27, "\u9f8d\u7f8e": 15, "\uff0c\u300c": 15, "\uff0efukaya": 15}, "titles": ["\u8b1d\u8f9e", "\u30d9\u30a4\u30ba\u6700\u9069\u5316 bayes", "\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 exchange", "\u63a2\u7d22\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0", "\u30b0\u30ea\u30c3\u30c9\u578b\u63a2\u7d22 mapper", "Nelder-Mead \u6cd5 minsearch", "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5 pamc", "\u304a\u554f\u3044\u5408\u308f\u305b", "Algorithm \u306e\u5b9a\u7fa9", "\u5171\u901a\u4e8b\u9805", "(\u958b\u767a\u8005\u5411\u3051)\u30e6\u30fc\u30b6\u30fc\u5b9a\u7fa9\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0\u30fb\u30bd\u30eb\u30d0\u30fc", "Solver \u306e\u5b9a\u7fa9", "\u5b9f\u884c\u65b9\u6cd5", "Welcome to ODAT-SE documentation!", "\u5165\u529b\u30d5\u30a1\u30a4\u30eb", "\u306f\u3058\u3081\u306b", "\u51fa\u529b\u30d5\u30a1\u30a4\u30eb", "analytical \u30bd\u30eb\u30d0\u30fc", "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc", "ODAT-SE \u306e\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb", "\u95a2\u9023\u30c4\u30fc\u30eb", "\u30d9\u30a4\u30ba\u6700\u9069\u5316", "\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22", "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb", "\u89e3\u6790\u95a2\u6570\u306e\u6700\u5c0f\u5316\u554f\u984c", "\u5236\u7d04\u5f0f\u3092\u9069\u7528\u3057\u305f\u30ec\u30d7\u30ea\u30ab\u4ea4\u63db\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed\u6cd5\u306b\u3088\u308b\u63a2\u7d22", "\u30b0\u30ea\u30c3\u30c9\u578b\u63a2\u7d22", "Nelder-Mead\u6cd5\u306b\u3088\u308b\u6700\u9069\u5316", "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u306b\u3088\u308b\u63a2\u7d22", "\u9806\u554f\u984c\u30bd\u30eb\u30d0\u30fc\u306e\u8ffd\u52a0"], "titleterms": {"#.": [2, 6], "-mead": [5, 27], "-se": [13, 15, 19], ".bayes": 1, ".info": 9, ".limitation": [9, 14], ".log": [14, 16], ".mapping": [9, 14], ".pickle": 16, ".runner": 9, ".txt": [1, 2, 4, 5, 6], "/result": [2, 6], "/trial": [2, 6], "[algorithm": [1, 14], "[algorithmparam": 1, "[base": 14, "[exchange": 2, "[minimize": 5, "[pamc": 6, "[param": [2, 4, 5, 6], "[runner": 14, "[solver": 14, "_neighborlist": 20, "_result": [2, 6], "_t": [2, 6], "affine": 9, "ais": 6, "algorithm": 8, "algorithmbase": 8, "analytical": 17, "annealed": 6, "annealing": 6, "base": 9, "bayes": 1, "bayesdata": 1, "best": [2, 6], "colormap": 4, "contents": 13, "documentation": 13, "domain": 8, "exchange": 2, "fx": 6, "importance": 6, "inequality": 9, "mapper": 4, "meshgrid": 8, "minsearch": 5, "nelder": [5, 27], "odat": [13, 15, 19], "odatse": [9, 20], "pa": 6, "pamc": 6, "population": 6, "rank": [2, 6], "region": 8, "res": 5, "result": 2, "runner": 16, "sampling": 6, "simplexdata": 5, "solver": 11, "status": 16, "time": 16, "to": 13, "trivialmapping": 9, "txt": [2, 6], "unlimited": 9, "welcome": 13, "\u304a\u554f\u3044": 7, "\u306b\u3064\u3044\u3066": [6, 9], "\u306b\u3088\u308b": [22, 25, 27, 28], "\u306f\u3058\u3081": 15, "\u30a2\u30eb\u30b4\u30ea\u30ba\u30e0": [1, 2, 3, 4, 6, 10], "\u30a2\u30f3\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": 19, "\u30a4\u30f3\u30b9\u30c8\u30fc\u30eb": 19, "\u30af\u30e9\u30b9": 8, "\u30b0\u30ea\u30c3\u30c9": [4, 26], "\u30b5\u30f3\u30d7\u30eb\u30d5\u30a1\u30a4\u30eb": [21, 22, 25, 26, 27, 28], "\u30b9\u30c6\u30c3\u30d7": 6, "\u30bb\u30af\u30b7\u30e7\u30f3": [1, 2, 4, 5, 6, 14], "\u30bd\u30eb\u30d0\u30fc": [10, 17, 18, 29], "\u30c0\u30a6\u30f3\u30ed\u30fc\u30c9": 19, "\u30c1\u30e5\u30fc\u30c8\u30ea\u30a2\u30eb": 23, "\u30c4\u30fc\u30eb": 20, "\u30d0\u30fc\u30b8\u30e7\u30f3": 15, "\u30d1\u30c3\u30b1\u30fc\u30b8": 19, "\u30d1\u30e9\u30e1\u30fc\u30bf": [1, 2, 4, 5, 6, 17], "\u30d5\u30a1\u30a4\u30eb": [1, 2, 4, 5, 6, 14, 16, 21, 22, 25, 26, 27, 28], "\u30d9\u30a4\u30ba": [1, 21], "\u30d9\u30f3\u30c1\u30de\u30fc\u30af": 29, "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0": 28, "\u30dd\u30d4\u30e5\u30ec\u30fc\u30b7\u30e7\u30f3\u30a2\u30cb\u30fc\u30ea\u30f3\u30b0\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": 6, "\u30de\u30eb\u30b3\u30d5": 2, "\u30e1\u30c3\u30b7\u30e5": [1, 2, 4, 6], "\u30e2\u30f3\u30c6\u30ab\u30eb\u30ed": [2, 22, 25], "\u30e6\u30fc\u30b6\u30fc": 10, "\u30e9\u30a4\u30bb\u30f3\u30b9": 15, "\u30ea\u30b9\u30bf\u30fc\u30c8": [1, 2, 4, 5, 6], "\u30ea\u30b9\u30c8": [2, 6], "\u30ec\u30d7\u30ea\u30ab": [2, 22, 25], "\u4e8b\u9805": 9, "\u4ea4\u63db": [2, 22, 25], "\u4f7f\u3044\u65b9": 20, "\u5165\u529b": [1, 2, 4, 5, 6, 14, 17, 21, 22, 25, 26, 27, 28], "\u5171\u901a": [9, 16], "\u51fa\u529b": [1, 2, 4, 5, 6, 16], "\u5316\u554f": 24, "\u53c2\u8003": 6, "\u53ef\u8996": [21, 22, 25, 26, 27, 28], "\u5408\u308f": 7, "\u5411\u3051": 10, "\u554f\u984c": [6, 18, 29], "\u578b\u63a2": [4, 26], "\u5834\u6240": [21, 22, 25, 26, 27, 28], "\u5b9a\u7fa9": [1, 2, 4, 6, 8, 10, 11], "\u5b9f\u884c": [12, 19, 21, 22, 25, 26, 27, 28], "\u5c65\u6b74": 15, "\u5fc5\u8981": 19, "\u63a2\u7d22": [3, 22, 25, 28], "\u6587\u732e": 6, "\u65b9\u6cd5": [12, 19], "\u6700\u5c0f": 24, "\u6700\u9069": [1, 21, 27], "\u6e96\u5099": [1, 2, 4, 5, 6], "\u74b0\u5883": 19, "\u76ee\u7684": 6, "\u7d04\u5f0f": 25, "\u7d50\u679c": [21, 22, 25, 26, 27, 28], "\u88dc\u52a9": [1, 2, 4, 6], "\u89e3\u6790": 24, "\u89e3\u8aac": [1, 2, 6], "\u8a08\u7b97": [21, 22, 25, 26, 27, 28], "\u8aac\u660e": [21, 22, 25, 26, 27, 28], "\u8b1d\u8f9e": 0, "\u8fd1\u508d": [2, 6], "\u8ffd\u52a0": 29, "\u9023\u9396": 2, "\u9069\u7528": 25, "\u958b\u767a": [10, 15], "\u95a2\u6570": [24, 29], "\u95a2\u9023": 20}}) \ No newline at end of file diff --git a/manual/v3.0.0/ja/solver/analytical.html b/manual/v3.0.0/ja/solver/analytical.html new file mode 100644 index 00000000..8b668f65 --- /dev/null +++ b/manual/v3.0.0/ja/solver/analytical.html @@ -0,0 +1,115 @@ + + + + + + + + analytical ソルバー — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

analytical ソルバー

+

analytical は探索アルゴリズムの性能評価を目的とした、 +定義済みのベンチマーク関数 \(f(x)\) を計算する Solver です。

+
+

入力パラメータ

+

solver セクション以下の funtion_name パラメータで用いる関数を指定します。

+
    +

  • function_name

    +

    形式: string型

    +

    説明: 関数名。以下の関数が選べます。

    +
      +

    • quadratics

      +
        +

      • 二次形式

        +
        +\[f(\vec{x}) = \sum_{i=1}^N x_i^2\]
        +
        • +

      • 最適値は \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • rosenbrock

      + +
      +\[f(\vec{x}) = \sum_{i=1}^{N-1} \left[ 100(x_{i+1} - x_i^2)^2 + (x_i - 1)^2 \right]\]
      +
        +

      • 最適値は \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 1)\)

        • +
      +
      • +

    • ackley

      + +
      +\[f(\vec{x}) = 20 + e - 20\exp\left[-0.2\sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}\right] - \exp\left[\frac{1}{N}\cos\left(2\pi x_i\right)\right]\]
      +
        +

      • 最適値は \(f(\vec{x}^*) = 0 \quad (\forall_i x_i^* = 0)\)

        • +
      +
      • +

    • himmerblau

      + +
      +\[f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2\]
      +
        +

      • 最適値は \(f(3,2) = f(-2.805118, 3.131312) = f(-3.779310, -3.283186) = f(3.584428, -1.848126) = 0\)

        • +
      +
      • +
    +
    • +
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/solver/index.html b/manual/v3.0.0/ja/solver/index.html new file mode 100644 index 00000000..3d8c734d --- /dev/null +++ b/manual/v3.0.0/ja/solver/index.html @@ -0,0 +1,68 @@ + + + + + + + + 順問題ソルバー — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

順問題ソルバー

+

順問題ソルバー Solver は探索パラメータ \(x\) から最適化したい \(f(x)\) を計算します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/start.html b/manual/v3.0.0/ja/start.html new file mode 100644 index 00000000..505af1e7 --- /dev/null +++ b/manual/v3.0.0/ja/start.html @@ -0,0 +1,162 @@ + + + + + + + + ODAT-SE のインストール — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

ODAT-SE のインストール

+
+

実行環境・必要なパッケージ

+
    +

  • python 3.9 以上

    +
    +
      +

    • 必要なpythonパッケージ

      +
      +
        +

      • tomli (>= 1.2)

        • +

      • numpy (>= 1.14)

        • +
      +
      +
      • +

    • Optional なパッケージ

      +
      +
        +

      • mpi4py (グリッド探索利用時)

        • +

      • scipy (Nelder-Mead法利用時)

        • +

      • physbo (ベイズ最適化利用時, ver. 2.0以上)

        • +
      +
      +
      • +
    +
    +
    • +
+
+
+

ダウンロード・インストール

+

下記に示す方法で、 ODAT-SE python パッケージと odatse コマンドがインストールできます。

+
    +

  • PyPI からのインストール(推奨)

    +
    +
      +

    • python3 -m pip install ODAT-SE

      +
      +
        +

      • --user オプションをつけるとローカル ($HOME/.local) にインストールできます

        • +

      • ODAT-SE[all] とすると Optional なパッケージも同時にインストールします

        • +
      +
      +
      • +
    +
    +
    • +

  • ソースコードからのインストール

    +
    +
      +

    1. git clone https://github.com/issp-center-dev/ODAT-SE

      2. +

    2. python3 -m pip install ./ODAT-SE

      +
      +
        +

      • pip のバージョンは 19 以上が必要です (python3 -m pip install -U pip で更新可能)

        • +
      +
      +
      3. +
    +
    +
    • +

  • サンプルファイルのダウンロード

    +
    +
      +

    • サンプルファイルはソースコードに同梱されています。

      • +

    • git clone https://github.com/issp-center-dev/ODAT-SE

      • +
    +
    +
    • +
+
+
+

実行方法

+

odatse コマンドは定義済みの最適化アルゴリズム Algorithm と順問題ソルバー Solver の組み合わせで解析を行います。

+
$ odatse input.toml
+
+
+

定義済みの Algorithm については 探索アルゴリズム を、 +Solver については 順問題ソルバー を参照してください。

+

2次元物質構造解析向け実験データ解析の順問題ソルバーは独立なパッケージとして提供されています。 +これらの解析を行う場合は別途パッケージと必要なソフトウェアをインストールしてください。 +現在は以下の順問題ソルバーが用意されています。

+
    +

  • 全反射高速陽電子回折 (TRHEPD) -- odatse-STR パッケージ

    • +

  • 表面X線回折 (SXRD) -- odatse-SXRD パッケージ

    • +

  • 低速電子線回折 (LEED) -- odatse-LEED パッケージ

    • +
+

Algorithm や Solver をユーザーが準備する場合は、 ODAT-SE パッケージを利用します。 +詳しくは (開発者向け)ユーザー定義アルゴリズム・ソルバー を参照してください。

+

なお、 プログラムを改造する場合など、 odatse コマンドをインストールせずに直接実行することも可能です。 +src/odatse_main.py を利用してください。

+
$ python3 src/odatse_main.py input.toml
+
+
+
+
+

アンインストール

+

ODAT-SE モジュールをアンインストールするには、以下のコマンドを実行します。

+
$ python3 -m pip uninstall ODAT-SE
+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tool.html b/manual/v3.0.0/ja/tool.html new file mode 100644 index 00000000..b81c020a --- /dev/null +++ b/manual/v3.0.0/ja/tool.html @@ -0,0 +1,118 @@ + + + + + + + + 関連ツール — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

関連ツール

+
+

odatse_neighborlist

+

離散空間をモンテカルロ探索する場合に使用する近傍リスト定義ファイルを +メッシュ定義ファイルから生成するツールです。

+

pip でインストールした場合は odatse と同様に bin 以下に odatse_neighborlist という名前でインストールされます。 +もしくは、ディレクトリ中の src/odatse_neighborlist.py を直接実行することも可能です。

+
+

使い方

+

引数としてメッシュ定義ファイルを渡します。 +生成される近傍リスト定義ファイルの名前は -o オプションで指定可能です。

+
$ odatse_neighborlist -o neighborlist.txt MeshData.txt
+
+
+

次のオプションが利用できます。

+
    +

  • -o output or --output output

    +
      +

    • 出力ファイル名 (default: neighborlist.txt)

      • +
    +
    • +

  • -u "unit1 unit2..." or --unit "unit1 unit2"

    +
      +

    • 各次元の長さスケール (default: すべて 1.0)

      +
        +

      • 空間次元の数だけ値を空白区切りで並べ、全体を引用符でくくってください

        • +
      +
      • +

    • 各座標はあらかじめこれらの長さスケールで除算されます

      • +
    +
    • +

  • -r radius or --radius radius

    +
      +

    • 近傍とみなされるユークリッド距離 (default: 1.0)

      • +

    • 距離は -u で除されたあとの座標に対して計算されます

      • +
    +
    • +

  • -q or --quiet

    +
      +

    • 進捗バーを表示しません

      • +

    • なお、進捗バーの表示には tqdm python パッケージが必要です

      • +
    +
    • +

  • --allow-selfloop

    +
      +

    • 自分自身を隣接リストに含めます（自己ループ）

      • +
    +
    • +

  • --check-allpairs

    +
      +

    • すべての点対に対して距離を計算します

      • +

    • デバッグ用のオプションです

      • +
    +
    • +
+

なお、 MPI を用いて計算を高速化できます。

+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/bayes.html b/manual/v3.0.0/ja/tutorial/bayes.html new file mode 100644 index 00000000..ef5f17e4 --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/bayes.html @@ -0,0 +1,196 @@ + + + + + + + + ベイズ最適化 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

ベイズ最適化

+

ここでは、ベイズ最適化を行いて Himmelblau関数の最小化問題を解析する方法について説明します。 +ベイズ最適化には PHYSBO を用います。 +事前に PHYSBO パッケージをインストールしておきます。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/bayes にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

また、計算結果を可視化するために sample フォルダ内の plot_himmel.py を利用します。

+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml を作成します。記述方法の詳細については「入力ファイル」の項を参照してください。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[algorithm]
+name = "bayes"
+seed = 12345
+
+[algorithm.param]
+min_list = [-6.0, -6.0]
+max_list = [ 6.0,  6.0]
+num_list = [61, 61]
+
+[algorithm.bayes]
+random_max_num_probes = 20
+bayes_max_num_probes = 40
+
+
+

[base], [solver], [runner] のセクションについては Nelder-Mead法による探索(minsearch)の場合と同じです。

+

[algorithm] セクションでは、使用するアルゴリスムとその設定をします。

+
    +

  • name は使用するアルゴリズムの名前です。このチュートリアルでは、ベイズ最適化を用いた解析を行うので、 bayes を指定します。

    • +

  • seed は乱数の初期値を指定します。

    • +
+

[algorithm.param] セクションでは、探索するパラメータの範囲や初期値を指定します。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • num_list はパラメータの各方向へのグリッド点の個数を指定します。

    • +
+

[algorithm.bayes] セクションでは、ベイズ最適化に関するハイパーパラメータを指定します。

+
    +

  • random_max_num_probes はランダムサンプリングの回数を指定します。

    • +

  • bayes_max_num_probes はベイズ最適化を行う回数を指定します。

    • +
+

ここではデフォルト値を用いるため省略しましたが、その他のパラメータについて詳細は「入力ファイル」の章を参照してください。

+
+
+

計算の実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、ODAT-SEパッケージをダウンロードしたディレクトリ直下にいることを仮定します。)

+
$ cd sample/analytical/bayes
+
+
+

メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。

+
$ python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

実行すると output ディレクトリの下に各ランクのフォルダが作成されます。 +以下の様な標準出力がされます。

+
# parameter
+random_max_num_probes = 10
+bayes_max_num_probes = 20
+score = TS
+interval = 5
+num_rand_basis = 5000
+value_01 =  5.10000
+value_02 =  4.90000
+R-factor = 0.037237314010261195
+0001-th step: f(x) = -0.037237 (action=150)
+   current best f(x) = -0.037237 (best action=150)
+
+value_01 =  4.30000
+value_02 =  3.50000
+
+  ...
+
+
+

最初に設定したパラメータのリスト、そのあとに各ステップでの候補パラメータと、 +その時の関数値 f(x) が出力されます。 +また、その時点での一番良いスコアを持つグリッドインデックス (action)とその場合の f(x) と変数が出力されます。 +最終的に推定されたパラメータは、 output/BayesData.txt に出力されます。

+

今回の場合は

+
#step x1 x2 fx x1_action x2_action fx_action
+0 -2.4 -0.7999999999999998 113.2192 -2.4 -0.7999999999999998 113.2192
+1 -2.4 -0.7999999999999998 113.2192 1.6000000000000005 4.600000000000001 263.12320000000045
+2 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.8000000000000007 -0.39999999999999947 28.995199999999958
+3 2.8000000000000007 -0.39999999999999947 28.995199999999958 4.800000000000001 5.800000000000001 1306.739200000001
+4 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.3999999999999995 2.5999999999999996 44.16320000000003
+5 2.8000000000000007 -0.39999999999999947 28.995199999999958 2.200000000000001 -5.2 623.6672
+6 2.8000000000000007 -0.39999999999999947 28.995199999999958 -1.1999999999999993 2.200000000000001 65.45919999999997
+7 4.200000000000001 -1.7999999999999998 23.619200000000067 4.200000000000001 -1.7999999999999998 23.619200000000067
+8 4.200000000000001 -1.7999999999999998 23.619200000000067 -2.5999999999999996 -0.1999999999999993 111.10720000000002
+9 4.200000000000001 -1.7999999999999998 23.619200000000067 0.6000000000000005 0.8000000000000007 130.00319999999994
+10 4.200000000000001 -1.7999999999999998 23.619200000000067 -0.5999999999999996 -0.5999999999999996 178.7552
+...
+38 3.200000000000001 1.8000000000000007 1.3952000000000133 3.200000000000001 -1.3999999999999995 8.051199999999973
+39 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.8 -3.0 3.433599999999999
+40 3.200000000000001 1.8000000000000007 1.3952000000000133 -3.0 -2.8 27.705600000000004
+41 3.6000000000000014 -1.7999999999999998 0.051200000000003215 3.6000000000000014 -1.7999999999999998 0.051200000000003215
+42 3.6000000000000014 -1.7999999999999998 0.051200000000003215 2.0 2.5999999999999996 22.457599999999996
+...
+
+
+

のように得られます。1列目にステップ数、2〜4列目にその時点での最高スコアを与える x1, x2 と f(x) が記載されます。 +続けて、そのステップで候補となった x1, x2 と f(x) が記載されます。 +今回の場合は41ステップ目で正しい解が得られていることがわかります。

+
+
+

計算結果の可視化

+

output/BayesData.txt を参照すると、何ステップ目のパラメータが最小スコアを与えたかがわかります。

+
$ python3 ../plot_himmel.py --xcol=1 --ycol=2 --format="-o" --output=output/res.pdf output/BayesData.txt
+$ python3 ../plot_himmel.py --xcol=4 --ycol=5 --format="o" --output=output/actions.pdf output/BayesData.txt
+
+
+

上記を実行すると output/actions.pdf と output/res.pdf が作成され、Himmelblau関数の関数値を表す等高線の上に、ベイズ最適化で評価したグリッド点と最小スコアを与える点の履歴がプロットされます。

+
+../_images/res_bayes_plot.png +
+

ベイズ最適化で評価したグリッド点(左図)と最小スコアを与える点の履歴(右図)

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/exchange.html b/manual/v3.0.0/ja/tutorial/exchange.html new file mode 100644 index 00000000..dbec616a --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/exchange.html @@ -0,0 +1,194 @@ + + + + + + + + レプリカ交換モンテカルロ法による探索 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

レプリカ交換モンテカルロ法による探索

+

ここでは、レプリカ交換モンテカルロ法を用いて Himmelblau関数の最小化問題を解析する方法について説明します。 +具体的な計算手順は minsearch の時と同様です。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/exchange にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml について説明します。記述方法の詳細については「入力ファイル」の項を参照してください。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[algorithm]
+name = "exchange"
+seed = 12345
+
+[algorithm.param]
+min_list = [3.0, 3.0]
+max_list = [6.0, 6.0]
+step_list = [0.3, 0.3]
+
+[algorithm.exchange]
+Tmin = 0.01
+Tmax = 100.0
+numsteps = 10000
+numsteps_exchange = 100
+nreplica_per_proc = 20
+
+
+

ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。

+

[base], [solver], [runner] のセクションについては Nelder-Mead法による探索(minsearch)の場合と同じです。

+

[algorithm] セクションでは、使用するアルゴリスムとその設定を行います。

+
    +

  • name は使用するアルゴリズムの名前です。このチュートリアルではレプリカ交換モンテカルロ法による解析を行うので、 exchange を指定します。

    • +
+

[algorithm.param] セクションでは、探索する連続なパラメータ空間の設定を行います。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • step_list はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。

    • +
+

[algorithm.exchange] サブセクションは、レプリカ交換モンテカルロ法のハイパーパラメータを指定します。

+
    +

  • numstep はモンテカルロ更新の回数です。

    • +

  • numsteps_exchange で指定した回数のモンテカルロ更新の後に、温度交換を試みます。

    • +

  • Tmin, Tmax はそれぞれ温度の下限・上限です。

    • +

  • Tlogspace が true の場合、温度を対数空間で等分割します。

    • +

  • nreplica_per_proc は 1つのMPIプロセスが受け持つレプリカの数を指定します。

    • +
+
+
+

計算の実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、ODAT-SEパッケージをダウンロードしたディレクトリ直下にいることを仮定します。)

+
$ cd sample/analytical/exchange
+
+
+

メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。

+
$ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数4のMPI並列を用いた計算を行っています。 +OpenMPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 mpiexec コマンドに --oversubscribe オプションを追加してください。

+

実行すると、 output ディレクトリの下に各ランクのフォルダが作成され、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した trial.txt ファイルと、実際に採択されたパラメータを記した result.txt ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。

+
# step walker T fx x1 x2
+0 0 0.01 170.0 0.0 0.0
+0 1 0.01123654800138751 187.94429125133564 5.155393113805774 -2.203493345018569
+0 2 0.012626001098748564 3.179380982615041 -3.7929742598748666 -3.5452766573635235
+0 3 0.014187266741165962 108.25464277273859 0.8127003489802398 1.1465364357510186
+0 4 0.01594159037455999 483.84183395038843 5.57417423682746 1.8381251624588506
+0 5 0.01791284454622004 0.43633134370869153 2.9868796504069426 1.8428384502208246
+0 6 0.020127853758499396 719.7992581349758 2.972577711255287 5.535680832873856
+0 7 0.022616759492228647 452.4691017123836 -5.899340424701358 -4.722667479627368
+0 8 0.025413430367026365 45.5355817998709 -2.4155554347674215 1.8769341969872393
+0 9 0.028555923019901074 330.7972369561986 3.717750630491217 4.466110964691396
+0 10 0.032086999973704504 552.0479484091458 5.575771168463163 2.684224163039442
+...
+
+
+

best_result.txt に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。

+
nprocs = 80
+rank = 3
+step = 8025
+walker = 17
+fx = 3.358076734724385e-06
+x1 = 2.9998063442504126
+x2 = 1.999754886043102
+
+
+

ODAT-SE の実装では1つのレプリカが様々な温度のサンプルを保持しています。各ランクフォルダにある result.txt には、各レプリカでサンプリングされたデータが記録されています。 +この全レプリカの結果から温度ごとのサンプルに整列し直したデータが output/result_T%.txt に出力されます。(% は温度点のindex。) +1列目がステップ、2列めがランク、3列目が目的関数の値、4列目以降がパラメータです。

+
# T = 0.014187266741165962
+0 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+1 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+2 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+3 3 108.25464277273859 0.8127003489802398 1.1465364357510186
+4 3 93.5034551820852 1.3377081691728905 0.8736706475438123
+5 3 81.40963740872147 1.4541906604820898 1.0420053981467825
+...
+
+
+
+
+

計算結果の可視化

+

result_T%.txt を図示することで f(x) の小さいパラメータがどこにあるかを推定することができます。 +以下のコマンドを入力すると 2次元パラメータ空間の図 res_T%.png が作成されます。

+
$ python3 ../plot_himmel.py --xcol=3 --ycol=4 --skip=20 --format="o" --output=output/res_T0.png output/result_T0.txt
+
+
+

作成された図を見ると、 f(x) の最小値を与える点の付近にサンプルが集中していることが分かります。温度Tのインデックスを変えると、高温ではサンプリング点が領域内に広く分布していること、温度を下げると極小点付近に集中することが見てとれます。

+
+../_images/res_exchange.png +
+

2次元パラメータ空間上のモンテカルロ法によるサンプリング点の分布。 \(T=\{35.02, 3.40, 0.33, 0.01\}\) の場合。

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/index.html b/manual/v3.0.0/ja/tutorial/index.html new file mode 100644 index 00000000..e7c6c249 --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/index.html @@ -0,0 +1,96 @@ + + + + + + + + チュートリアル — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

チュートリアル

+

このチュートリアルでは、解析関数の最小化問題を例として、ODAT-SEによる逆問題解析の方法を説明します。 +ODAT-SEには、逆問題を解くためのアルゴリズムとして以下の5つの手法が用意されています。

+
    +

  • minsearch

    +

    Nealder-Mead法

    +
    • +

  • mapper_mpi

    +

    与えられたパラメータの探索グリッドを全探索する

    +
    • +

  • bayes

    +

    ベイズ最適化

    +
    • +

  • exchange

    +

    レプリカ交換モンテカルロ法

    +
    • +

  • pamc

    +

    ポピュレーションアニーリング法

    +
    • +
+

以下ではこれらのアルゴリズムを用いた実行方法を説明します。 +また、制約式を用いて探索範囲を制限できる [runner.limitation] セクションを使用した実行方法も説明しています。 +最後に、自分で順問題ソルバーを定義する簡単な例について説明します。

+
+ +
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/intro.html b/manual/v3.0.0/ja/tutorial/intro.html new file mode 100644 index 00000000..a40afdd8 --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/intro.html @@ -0,0 +1,74 @@ + + + + + + + + 解析関数の最小化問題 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

解析関数の最小化問題

+

順問題ソルバーの例として ODAT-SE に含まれている Analytical ソルバーの中から Himmelblau関数の最小化問題を取り上げます。 +Himmelblau関数は次の表式で表される2変数関数で、複数の極小点を持ち、最適化アルゴリズムの性能評価に使われます。

+
+\[f(x,y) = (x^2+y-11)^2 + (x+y^2-7)^2\]
+

最小値 \(f(x,y)=0\) を与える \((x,y)\) は \((3.0, 2.0)\), \((-2.805118, 3.131312)\), \((-3.779310, -3.283186)\), \((3.584428, -1.848126)\) です。

+
+../_images/plot_himmelblau.png +
+

Himmelblau関数の plot。

+
+
+

[1] D. Himmelblau, Applied Nonlinear Programming, McGraw-Hill, 1972.

+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/limitation.html b/manual/v3.0.0/ja/tutorial/limitation.html new file mode 100644 index 00000000..f9b61d1a --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/limitation.html @@ -0,0 +1,231 @@ + + + + + + + + 制約式を適用したレプリカ交換モンテカルロ法による探索 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

制約式を適用したレプリカ交換モンテカルロ法による探索

+

ここでは、 [runner.limitation] セクションに設定できる制約式機能のチュートリアルを示します。 +例として、レプリカ交換モンテカルロ法を用いてHimmelblauの最小値を探索する計算に制約式を適用します。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/limitation にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • input.toml

    +

    メインプログラムの入力ファイル。

    +
    • +

  • ref.txt

    +

    計算が正しく実行されたか確認するためのファイル (本チュートリアルを行うことで得られる best_result.txt の回答)。

    +
    • +

  • hist2d_limitation_sample.py

    +

    可視化のためのツール。

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

以下、これらのファイルについて説明したあと、実際の計算結果を紹介します。

+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml について説明します。 +詳細については「入力ファイル」の章を参照してください。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "exchange"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+unit_list = [0.3, 0.3]
+
+[algorithm.exchange]
+Tmin = 1.0
+Tmax = 100000.0
+numsteps = 10000
+numsteps_exchange = 100
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.limitation]
+co_a = [[1, -1],[1, 1]]
+co_b = [[0], [-1]]
+
+
+

[base] セクションはメインプログラム全体のパラメータです。

+
    +

  • dimension は最適化したい変数の個数です。今の場合は2つの変数の最適化を行うので、 2 を指定します。

    • +

  • output_dir は出力先のディレクトリを指定します。

    • +
+

[algorithm] セクションでは、用いる探索アルゴリズムを設定します。

+
    +

  • name は使用するアルゴリズムの名前です。このチュートリアルでは交換モンテカルロ法を用いるので "exchange" を指定します。

    • +

  • seed は擬似乱数生成器に与える乱数の種です。

    • +
+

[algorithm.param] サブセクションは、最適化したいパラメータの範囲などを指定します。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • unit_list はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。

    • +
+

[algorithm.exchange] サブセクションは、交換モンテカルロ法のハイパーパラメータを指定します。

+
    +

  • numstep はモンテカルロ更新の回数です。

    • +

  • numsteps_exchange で指定した回数のモンテカルロ更新の後に、温度交換を試みます。

    • +

  • Tmin, Tmax はそれぞれ温度の下限・上限です。

    • +

  • Tlogspace が true の場合、温度を対数空間で等分割します。指定がない場合のデフォルト値は true です。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。

+
    +

  • name は使用するソルバーの名前です。このチュートリアルでは analytical ソルバーに含まれる解析関数の解析を行います。

    • +

  • function_name は analytical ソルバー内の関数名を指定します。

    • +
+

[runner] セクションの [runner.limitation] サブセクションで制約式を設定します。 +現在、制約式は \(N\) 次元のパラメータ \(x\) 、 \(M\) 行 \(N\) 列の行列 \(A\) 、 +\(M\) 次元の縦ベクトル \(b\) から定義される \(Ax+b>0\) の制約式が利用可能です。 +パラメータとしては、以下の項目が設定可能です。

+
    +

  • co_a は行列 \(A\) を設定します。

    • +

  • co_b は縦ベクトル \(b\) を設定します。

    • +
+

パラメータの詳しい設定方法はマニュアル内「入力ファイル」項の「 [limitation] セクション」を参照してください。 +今回は

+
+\[\begin{split}x_{1} - x_{2} > 0 \\ +x_{1} + x_{2} - 1 > 0\end{split}\]
+

の制約式を課して実行しています。

+
+
+

計算の実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します。)

+
$ cd sample/analytical/limitation
+
+
+

次に、メインプログラムを実行します。計算時間は通常のPCで20秒程度で終わります。

+
$ mpiexec -np 10 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数10のMPI並列を用いた計算を行っています。 +Open MPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 mpiexec コマンドに --oversubscribe オプションを追加してください。

+

実行すると、 output フォルダが生成され、その中に各ランクのフォルダが作成されます。 +更にその中には、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した trial.txt ファイルと、実際に採択されたパラメータを記した result.txt ファイルが作成されます。 +ともに書式は同じで、最初の2列がステップ数とプロセス内のwalker 番号、次が温度、3列目が目的関数の値、4列目以降がパラメータです。 +以下は、 output/0/result.txt ファイルの冒頭部分です。

+
# step walker T fx x1 x2
+0 0 1.0 187.94429125133564 5.155393113805774 -2.203493345018569
+1 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+2 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+3 0 1.0 148.23606736778044 4.9995614992887525 -2.370212436322816
+...
+
+
+

最後に、 output/best_result.txt に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。

+
nprocs = 10
+rank = 2
+step = 4523
+walker = 0
+fx = 0.00010188398524402734
+x1 = 3.584944906595298
+x2 = -1.8506985826548874
+
+
+

なお、一括計算するスクリプトとして do.sh を用意しています。 +do.sh では best_result.txt と ref.txt の差分も比較しています。 +以下、説明は割愛しますが、その中身を掲載します。

+
#!/bin/bash
+
+mpiexec -np 10 --oversubscribe python3 ../../../src/odatse_main.py input.toml
+
+echo diff output/best_result.txt ref.txt
+res=0
+diff output/best_result.txt ref.txt || res=$?
+if [ $res -eq 0 ]; then
+  echo TEST PASS
+  true
+else
+  echo TEST FAILED: best_result.txt and ref.txt differ
+  false
+fi
+
+
+
+
+

計算結果の可視化

+

result.txt を図示して、制約式を満たした座標のみを探索しているかを確認します。 +以下のコマンドを実行すると2次元パラメータ空間の図が <実行日>_histogram フォルダ内に作成されます。 +生成されるヒストグラムは、burn-in期間として最初の1000ステップ分の探索を捨てたデータを使用しています。

+
$ python3 hist2d_limitation_sample.py -p 10 -i input.toml -b 0.1
+
+
+

作成された図には2本の直線 \(x_{1} - x_{2} = 0\), \(x_{1} + x_{2} - 1 = 0\) と探索結果(事後確率分布のヒストグラム)を図示しています。 +図を見ると \(x_{1} - x_{2} > 0\), \(x_{1} + x_{2} - 1 > 0\) の範囲のみ探索をしていることが確認できます。 +以下に図の一部を掲載します。

+
+../_images/res_limitation.png +
+

サンプルされたパラメータと確率分布。横軸は x1 , 縦軸は x2 を表す。

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/mapper.html b/manual/v3.0.0/ja/tutorial/mapper.html new file mode 100644 index 00000000..504c238c --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/mapper.html @@ -0,0 +1,173 @@ + + + + + + + + グリッド型探索 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

グリッド型探索

+

ここでは、グリッド型探索を行い Himmelblau関数の最小化問題を解析する方法について説明します。 +グリッド型探索はMPI並列化に対応しています。具体的な計算手順は minsearch の場合と同様です。 +探索グリッドはパラメータを元にプログラム内部で生成します。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/mapper にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • plot_colormap_2d.py

    +

    計算結果を可視化するためのプログラム

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml について説明します。記述方法の詳細については「入力ファイル」の項を参照してください。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.log]
+interval = 20
+
+[algorithm]
+name = "mapper"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+num_list = [31, 31]
+
+
+

[base], [solver], [runner] のセクションについては Nelder-Mead法による探索(minsearch)の場合と同じです。

+

[algorithm] セクションでは、使用するアルゴリスムとその設定を行います。

+
    +

  • name は使用するアルゴリズムの名前です。このチュートリアルでは、グリッド探索による解析を行うので、 mapper を指定します。

    • +
+

[algorithm.param] セクションで探索するパラメータのグリッドを指定します。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • num_list はパラメータの各方向へのグリッド点の個数を指定します。

    • +
+

ここではデフォルト値を用いるため省略しましたが、その他のパラメータについて詳細は「入力ファイル」の章を参照してください。

+
+
+

計算の実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、ODAT-SEパッケージをダウンロードしたディレクトリの直下にいることを仮定します。)

+
$ cd sample/analytical/mapper
+
+
+

メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。

+
$ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数4のMPI並列を用いた計算を行っています。 +実行すると output ディレクトリとその下に各ランクのフォルダが作成され、ランクごとの計算結果が出力されます。 +同時に、以下の様な出力が標準出力に書き出されます。

+
Make ColorMap
+Iteration : 1/240
+Iteration : 2/240
+Iteration : 3/240
+Iteration : 4/240
+Iteration : 5/240
+Iteration : 6/240
+Iteration : 7/240
+...
+
+
+

x1, x2 に各メッシュでの候補パラメータと、その時の関数値が出力されます。 +最終的にグリッド上の全ての点で計算された関数値が output/ColorMap.txt に出力されます。 +今回の場合は、

+
-6.000000 -6.000000 890.000000
+-5.600000 -6.000000 753.769600
+-5.200000 -6.000000 667.241600
+-4.800000 -6.000000 622.121600
+-4.400000 -6.000000 610.729600
+-4.000000 -6.000000 626.000000
+-3.600000 -6.000000 661.481600
+-3.200000 -6.000000 711.337600
+-2.800000 -6.000000 770.345600
+...
+
+
+

のような結果が得られ、 +1列目、2列目に x1, x2 の値、3列目に関数値が記載されます。

+
+
+

計算結果の可視化

+

ColorMap.txt を図示することで、関数の値が小さいパラメータがどこにあるかを推定することができます。そのような 2次元パラメータ空間のプロットを作成するプログラムが plot_colormap_2d.py に用意されています。

+
$ python3 plot_colormap_2d.py
+
+
+

上記を実行すると ColorMapFig.png が作成され、Himmelblau関数の関数値を表す等高線の上に、各グリッド点で評価した関数値がカラーマップとしてプロットされます。

+
+../_images/res_mapper.png +
+

グリッド型探索における2次元パラメータ空間上での関数値のカラーマップ。

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/minsearch.html b/manual/v3.0.0/ja/tutorial/minsearch.html new file mode 100644 index 00000000..03a0db6b --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/minsearch.html @@ -0,0 +1,192 @@ + + + + + + + + Nelder-Mead法による最適化 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + +
+ + +
+

Nelder-Mead法による最適化

+

ここでは、Nelder-Mead法を用いて Himmelblau関数の最小値を探索する方法について説明します。 +具体的な計算手順は以下の通りです。

+
    +

  1. 入力ファイルを用意する

    +

    入力パラメータをTOML形式で記述した入力ファイルを作成します。

    +
    2. +

  2. メインプログラムを実行する

    +

    src/odatse_main.py を用いて計算を実行し、最適化問題を解きます。

    +
    3. +
+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/minsearch にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+

また、計算結果を可視化するために sample フォルダ内の plot_himmel.py を利用します。

+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml を作成します。記述方法の詳細については「入力ファイル」の項を参照してください。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.log]
+interval = 20
+
+[algorithm]
+name = "minsearch"
+seed = 12345
+
+[algorithm.param]
+min_list = [-6.0, -6.0]
+max_list = [ 6.0,  6.0]
+initial_list = [0, 0]
+
+
+

[base] セクションではプログラム全体で利用するパラメータを設定します。

+
    +

  • dimension は最適化したい変数の個数です。Himmelblau関数は 2変数関数ですので、今の場合は 2 を指定します。

    • +

  • output_dir は出力先のディレクトリを指定します。

    • +
+

[solver] セクションではメインプログラムの内部で使用するソルバーとその設定を指定します。

+
    +

  • name は使用するソルバーの名前です。このチュートリアルでは analytical ソルバーに含まれる解析関数の解析を行います。

    • +

  • function_name は analytical ソルバー内の関数名を指定します。

    • +
+

[runner] セクションでは、逆問題解析アルゴリズムからソルバーの呼び出しに関する設定を行います。

+
    +

  • [runner.log] の interval は、ログ出力の頻度を指定します。 interval 回の繰り返し毎にログを出力します。

    • +
+

[algorithm] セクションでは、使用するアルゴリスムとその設定をします。

+
    +

  • name は使用するアルゴリズムの名前です。このチュートリアルでは、Nelder-Mead法 を用いた解析を行うので、 minsearch を指定します。

    • +

  • seed は乱数の初期値を指定します。

    • +
+

[algorithm.param] セクションでは、探索するパラメータの範囲や初期値を指定します。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • initial_list は初期値を指定します。

    • +
+

ここではデフォルト値を用いるため省略しましたが、その他のパラメータ、例えばNelder-Mead法で使用する収束判定などについては、[algorithm] セクションで行うことが可能です。 +詳細については「入力ファイル」の章を参照してください。

+
+
+

計算の実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します。(以下では、ODAT-SE パッケージをダウンロードしたディレクトリの直下にいることを仮定します。)

+
$ cd sample/analytical/minsearch
+
+
+

メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。

+
$ python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

実行すると、以下の様な出力がされます。

+
Optimization terminated successfully.
+         Current function value: 0.000000
+         Iterations: 40
+         Function evaluations: 79
+iteration: 40
+len(allvecs): 41
+step: 0
+allvecs[step]: [0. 0.]
+step: 1
+allvecs[step]: [0.375 0.375]
+step: 2
+allvecs[step]: [0.0625 0.9375]
+step: 3
+allvecs[step]: [0.65625 1.46875]
+step: 4
+allvecs[step]: [0.328125 2.859375]
+...
+
+
+

x1, x2 に各ステップでの候補パラメータと、その時の関数値が出力されます。 +最終的に推定されたパラメータは output/res.dat に出力されます。今の場合、

+
fx = 4.2278370361994904e-08
+x1 = 2.9999669562950175
+x2 = 1.9999973389336225
+
+
+

が得られ、最小値を与える解の一つが求められたことが分かります。

+
+
+

計算結果の可視化

+

Nelder-Mead法による解の探索の経路は output/0/SimplexData.txt に出力されています。 +これをプロットするツールが sample/plot_himmel.py に用意されています。

+
$ python3 ../plot_himmel.py --xcol=1 --ycol=2 --output=output/res.pdf output/0/SimplexData.txt
+
+
+

上記を実行すると output/res.pdf が出力されます。

+
+../_images/res_minsearch.png +
+

Nelder-Mead法を用いた Himmelblau 関数の最小値探索。黒線は Himmelblau関数の関数値を表す等高線、青色のシンボルは探索経路。

+
+
+

Himmelblau関数の関数値を表す等高線の上に Nelder-Mead法による探索の経路がプロットされます。初期値 (0, 0) からスタートして最小値を与える解の一つ (3, 2) に到達していることが分かります。

+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/pamc.html b/manual/v3.0.0/ja/tutorial/pamc.html new file mode 100644 index 00000000..70892e4b --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/pamc.html @@ -0,0 +1,204 @@ + + + + + + + + ポピュレーションアニーリングによる探索 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

ポピュレーションアニーリングによる探索

+

ここでは、ポピュレーションアニーリングを用いて Himmelblau関数の最小化問題を解析する方法について説明します。 +具体的な計算手順は minsearch の時と同様です。

+
+

サンプルファイルの場所

+

サンプルファイルは sample/analytical/pamc にあります。 +フォルダには以下のファイルが格納されています。

+
    +

  • input.toml

    +

    メインプログラムの入力ファイル

    +
    • +

  • do.sh

    +

    本チュートリアルを一括計算するために準備されたスクリプト

    +
    • +
+
+
+

入力ファイルの説明

+

メインプログラム用の入力ファイル input.toml について説明します。記述方法の詳細については「入力ファイル」の項を参照してください。

+
[base]
+dimension = 2
+output_dir = "output"
+
+[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+[runner]
+[runner.log]
+interval = 20
+
+[algorithm]
+name = "pamc"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+step_list = [0.1, 0.1]
+
+[algorithm.pamc]
+Tmin = 1.0
+Tmax = 100.0
+Tnum = 21
+Tlogspace = true
+numsteps_annealing = 100
+nreplica_per_proc = 100
+
+
+

ここではこの入力ファイルを簡単に説明します。 +詳細は入力ファイルのレファレンスを参照してください。

+

[base], [solver], [runner] のセクションについては Nelder-Mead法による探索(minsearch)の場合と同じです。

+

[algorithm] セクションでは、使用するアルゴリスムとその設定を行います。

+
    +

  • name は使用するアルゴリズムの名前です。このチュートリアルでは、ポピュレーションアニーリング法による解析を行うので、 pamc を指定します。

    • +
+

[algorithm.param] セクションでは、探索する連続なパラメータ空間の設定を行います。

+
    +

  • min_list と max_list はそれぞれ探索範囲の最小値と最大値を指定します。

    • +

  • step_list はモンテカルロ更新の際の変化幅(ガウス分布の偏差)です。

    • +
+

[algorithm.pamc] セクションは、ポピュレーションアニーリングのハイパーパラメータを指定します。

+
    +

  • numsteps_annealing で指定した回数のモンテカルロ更新の後に、逆温度を増やします (温度を下げます)。

    • +

  • bmin, bmax はそれぞれ逆温度の下限・上限です。

    • +

  • Tnum は計算する温度・逆温度の点数です。

    • +

  • Tlogspace が true の場合、温度を対数空間で等分割します

    • +

  • nreplica_per_proc はMPIプロセスひとつが受け持つ計算レプリカの数です。

    • +
+
+
+

計算の実行

+

最初にサンプルファイルが置いてあるフォルダへ移動します。(以下、本ソフトウェアをダウンロードしたディレクトリ直下にいることを仮定します。)

+
$ cd sample/analytical/pamc
+
+
+

メインプログラムを実行します。計算時間は通常のPCで数秒程度で終わります。

+
$ mpiexec -np 4 python3 ../../../src/odatse_main.py input.toml | tee log.txt
+
+
+

ここではプロセス数4のMPI並列を用いた計算を行っています。 +OpenMPI を用いる場合で、使えるコア数よりも要求プロセス数の方が多い時には、 mpiexec コマンドに --oversubscribe オプションを追加してください。

+

実行すると、 output ディレクトリの下に各ランクのフォルダが作成され、温度ごとに、各モンテカルロステップで評価したパラメータおよび目的関数の値を記した trial_TXXX.txt ファイル(XXX は温度点の番号)と、実際に採択されたパラメータを記した result_TXXX.txt ファイル、さらにそれぞれを結合した trial.txt, result.txt ファイルが生成されます。 +それぞれ書式は同じで、最初の2列がステップ数とプロセス内の walker (replica) 番号、次が(逆)温度、3列目が目的関数の値、4列目以降がパラメータです。 +最後の2 列は、 walker の重み (Neal-Jarzynski weight) と祖先(計算を開始したときのレプリカ)の番号です。

+
# step walker T fx x1 x2 weight ancestor
+0 0 100.0 187.94429125133564 5.155393113805774 -2.203493345018569 1.0 0
+0 1 100.0 3.179380982615041 -3.7929742598748666 -3.5452766573635235 1.0 1
+0 2 100.0 108.25464277273859 0.8127003489802398 1.1465364357510186 1.0 2
+0 3 100.0 483.84183395038843 5.57417423682746 1.8381251624588506 1.0 3
+0 4 100.0 0.43633134370869153 2.9868796504069426 1.8428384502208246 1.0 4
+0 5 100.0 719.7992581349758 2.972577711255287 5.535680832873856 1.0 5
+0 6 100.0 452.4691017123836 -5.899340424701358 -4.722667479627368 1.0 6
+0 7 100.0 45.5355817998709 -2.4155554347674215 1.8769341969872393 1.0 7
+0 8 100.0 330.7972369561986 3.717750630491217 4.466110964691396 1.0 8
+0 9 100.0 552.0479484091458 5.575771168463163 2.684224163039442 1.0 9
+0 10 100.0 32.20027165958588 1.7097039347500953 2.609443449748964 1.0 10
+...
+
+
+

output/best_result.txt に、目的関数が最小となったパラメータとそれを得たランク、モンテカルロステップの情報が書き込まれます。

+
nprocs = 4
+rank = 3
+step = 1806
+walker = 74
+fx = 4.748689609377718e-06
+x1 = -2.805353724219707
+x2 = 3.131045687296453
+
+
+

最後に、 output/fx.txt には、各温度ごとの統計情報が記録されます。

+
# $1: 1/T
+# $2: mean of f(x)
+# $3: standard error of f(x)
+# $4: number of replicas
+# $5: log(Z/Z0)
+# $6: acceptance ratio
+0.01 130.39908953806298 6.023477428315198 400 0.0 0.9378
+0.01258925411794167 83.6274790817115 3.83620542622489 400 -0.2971072297035158 0.930325
+0.015848931924611134 60.25390522675298 2.73578884504734 400 -0.5426399088244793 0.940375
+0.01995262314968879 47.20146188151557 2.3479083531465976 400 -0.7680892360649545 0.93715
+0.025118864315095794 41.118822390166315 1.8214854089575818 400 -0.9862114670289625 0.9153
+...
+
+
+

1列目は温度・逆温度で、2・3列目は目的関数 \(f(x)\) の期待値と標準誤差、4列目はレプリカの個数、5列目は分配関数の比の対数 \(\log(Z_n/Z_0)\) (\(Z_0\) は最初の温度点における分配関数)、6列目はモンテカルロ更新の採択率です。

+
+
+

計算結果の可視化

+

result_T%.txt を図示することで f(x) の小さいパラメータがどこにあるかを推定することができます。 +以下のコマンドを入力すると2次元パラメータ空間の図 res_T%.png が作成されます。 +シンボルの色は目的関数の値に対応します。

+
$ python3 plot_result_2dmap.py
+
+
+

作成された図を見ると、 T を小さくするごとに f(x) の最小値を与える点の付近にサンプルが集中していることがわかります。

+
+../_images/res_pamc.png +
+

サンプルされたパラメータ。横軸は x1 , 縦軸は x2 を、色は T (左図), f(x) (右図)を表す。

+
+
+
+
+ + +
+ + + + + \ No newline at end of file diff --git a/manual/v3.0.0/ja/tutorial/solver_simple.html b/manual/v3.0.0/ja/tutorial/solver_simple.html new file mode 100644 index 00000000..5bb96d06 --- /dev/null +++ b/manual/v3.0.0/ja/tutorial/solver_simple.html @@ -0,0 +1,137 @@ + + + + + + + + 順問題ソルバーの追加 — ODAT-SE 3.0-dev ドキュメント + + + + + + + + + + + + + + +
+ + +
+

順問題ソルバーの追加

+
+

ベンチマーク関数ソルバー

+

ODAT-SEでは探索アルゴリズムのテストに利用できる順問題ソルバーとして analytical ソルバーを用意しています。

+

analytical ソルバーを使うには、入力ファイルの [solver] セクションの name を "analytical" に設定し、 function_name パラメータを用いてベンチマーク関数 \(f(x)\) を選択します。 +たとえば、 Himmelblau 関数を用いる場合には

+
[solver]
+name = "analytical"
+function_name = "himmelblau"
+
+
+

とします。 +利用可能な関数の詳細は analytical ソルバーのリファレンス を参照してください。

+
+
+

順問題ソルバーの追加

+

ユーザ定義の順問題ソルバーを定義・解析する一番簡単な方法は、 analytical ソルバーに追加することです。 +ここでは例として、 Booth関数

+
+\[f(x,y) = (x+2y-7)^{2} + (2x+y-5)^{2}\]
+

を追加してみましょう。(最小値は \(f(1,3) = 0\))

+

そのためには、 ODAT-SEのソースコードをダウンロードし、ファイルを編集する必要があります。 +ダウンロード方法や、ソースコードからの実行方法などは、 インストールページ を参照してください。

+

analytical ソルバーは src/odatse/solver/analytical.py に定義されているので、これを編集します。

+

まず、 booth 関数を定義します。

+
def booth(xs: np.ndarray) -> float:
+    """Booth function
+
+    it has one global minimum f(xs) = 0 at xs = [1,3].
+    """
+
+    if xs.shape[0] != 2:
+        raise RuntimeError(
+            f"ERROR: booth expects d=2 input, but receives d={xs.shape[0]} one"
+        )
+    return (xs[0] + 2 * xs[1] - 7.0) ** 2 + (2 * xs[0] + xs[1] - 5.0) ** 2
+
+
+

つぎに、入力ファイルの solver.function_name パラメータで booth 関数を指定できるようにするために、Solver クラスのコンストラクタ (__init__) 中の if 分岐に以下のコードを挿入します。

+
elif function_name == "booth":
+        self.set_function(booth)
+
+
+

この改造した analytical ソルバーでは、 Booth 関数の最適化が行なえます。 +たとえばNelder-Mead 法による最適化は、以下の入力ファイル (input.toml) を

+
[base]
+dimension = 2
+output_dir = "output"
+
+[algorithm]
+name = "minsearch"
+seed = 12345
+
+[algorithm.param]
+max_list = [6.0, 6.0]
+min_list = [-6.0, -6.0]
+initial_list = [0, 0]
+
+[solver]
+name = "analytical"
+function_name = "booth"
+
+
+

src/odatse_main.py に渡せば実行可能です。

+
$ python3 src/odatse_main.py input.toml
+
+... skipped ...
+
+Iterations: 38
+Function evaluations: 75
+Solution:
+x1 = 1.0000128043523089
+x2 = 2.9999832920260863
+
+
+
+
+ + +
+ + + + + \ No newline at end of file