pyfemtet 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

pyfemtet/opt/_femopt.py

@@ -12,12 +12,12 @@ from traceback import print_exception
 # 3rd-party
 import numpy as np
 import pandas as pd
-from dask.distributed import LocalCluster, Client, Worker
+from dask.distributed import LocalCluster, Client
 
 # pyfemtet relative
 from pyfemtet.opt.interface import FEMInterface, FemtetInterface
 from pyfemtet.opt.optimizer import AbstractOptimizer, OptunaOptimizer
-from pyfemtet.opt.visualization.process_monitor.application import main as process_monitor_main
+from pyfemtet.opt.visualization._process_monitor.application import main as process_monitor_main
 from pyfemtet.opt._femopt_core import (
     _check_bound,
     _is_access_gogh,
@@ -28,13 +28,17 @@ from pyfemtet.opt._femopt_core import (
     OptimizationStatus,
     logger,
 )
-from pyfemtet.message import Msg, encoding
-from pyfemtet.opt.parameter import Parameter, Expression
+from pyfemtet._message import Msg, encoding
+from pyfemtet.opt.optimizer.parameter import Parameter, Expression
+from pyfemtet._warning import experimental_feature
 
+from dask import config as cfg
+cfg.set({'distributed.scheduler.worker-ttl': None})
 
-def add_worker(client, worker_name):
+
+def add_worker(client, worker_name, n_workers=1):
     import sys
-    from subprocess import Popen, DEVNULL
+    from subprocess import Popen, DEVNULL, PIPE
 
     current_n_workers = len(client.nthreads().keys())
 
@@ -42,39 +46,59 @@ def add_worker(client, worker_name):
         f'{sys.executable} -m dask worker '
         f'{client.scheduler.address} '
         f'--nthreads 1 '
-        f'--nworkers 1 '
-        f'--name {worker_name} '
-        f'--no-nanny',
+        f'--nworkers {n_workers} '
+        f'--name {worker_name} ',  # A unique name for this worker like ‘worker-1’. If used with -nworkers then the process number will be appended like name-0, name-1, name-2, …
+        # --no-nanny option は --nworkers と併用できない
         shell=True,
         stderr=DEVNULL,
         stdout=DEVNULL,
     )
 
     # worker が増えるまで待つ
-    client.wait_for_workers(n_workers=current_n_workers + 1)
-
+    client.wait_for_workers(n_workers=current_n_workers + n_workers)
 
 
 class FEMOpt:
     """Class to control FEM interface and optimizer.
 
     Args:
-        fem (FEMInterface, optional): The finite element method interface. Defaults to None. If None, automatically set to FemtetInterface.
-        opt (AbstractOptimizer):
-        history_path (str, optional): The path to the history file. Defaults to None. If None, '%Y_%m_%d_%H_%M_%S.csv' is created in current directory.
-        scheduler_address (str or None): If cluster processing, set this parameter like "tcp://xxx.xxx.xxx.xxx:xxxx".
-
-    Attributes:
-        fem (FEMInterface): The interface of FEM system.
-        opt (AbstractOptimizer): The optimizer.
-        scheduler_address (str or None): Dask scheduler address. If None, LocalCluster will be used.
-        client (Client): Dask client. For detail, see dask documentation.
-        status (OptimizationStatus): Entire process status. This contains dask actor.
-        history(History): History of optimization process. This contains dask actor.
-        history_path (str): The path to the history (.csv) file.
-        worker_status_list([OptimizationStatus]): Process status of each dask worker.
-        monitor_process_future(Future): Future of monitor server process. This is dask future.
-        monitor_server_kwargs(dict): Monitor server parameter. Currently, the valid arguments are hostname and port.
+        fem (FEMInterface, optional):
+            The FEM software interface.
+            Defaults to None (automatically set to :class:`FemtetInterface`).
+
+        opt (AbstractOptimizer, optional):
+            The numerical optimizer object.
+            Defaults to None (automatically set to :class:`OptunaOptimizer`
+            with :class:`optuna.samplers.TPESampler`).
+
+        history_path (str, optional):
+            The path to the history file.
+            Defaults to None.
+            If None, '%Y_%m_%d_%H_%M_%S.csv' is created in current directory.
+
+        scheduler_address (str, optional):
+            When performing cluster computing, please specify the address
+            of the scheduler computer here.
+
+            See Also:
+                https://pyfemtet.readthedocs.io/en/stable/pages/usage_pages/how_to_deploy_cluster.html
+
+    .. Example の中について、reST ではリストだと改行できないので、リストにしない
+
+    Examples:
+
+        When specifying and opening a femprj and model, we write
+
+            >>> from pyfemtet.opt import FEMOpt, FemtetInterface  # doctest: +SKIP
+            >>> fem = FemtetInterface(femprj_path='path/to/project.femprj', model_name='NewModel')  # doctest: +SKIP
+            >>> femopt = FEMOpt(fem=fem)  # doctest: +SKIP
+
+        When specifying optimization algorithm, we write
+
+            >>> from optuna.samplers import TPESampler  # doctest: +SKIP
+            >>> from pyfemtet.opt import FEMOpt, OptunaOptimizer  # doctest: +SKIP
+            >>> opt = OptunaOptimizer(sampler_class=TPESampler, sampler_kwargs=dict(n_startup_trials=10))  # doctest: +SKIP
+            >>> femopt = FEMOpt(opt=opt)  # doctest: +SKIP
 
     """
 
@@ -111,6 +135,7 @@ class FEMOpt:
         self.monitor_process_future = None
         self.monitor_server_kwargs = dict()
         self.monitor_process_worker_name = None
+        self._hv_reference = None
 
     # multiprocess 時に pickle できないオブジェクト参照の削除
     def __getstate__(self):
@@ -133,25 +158,40 @@ class FEMOpt:
     def add_parameter(
             self,
             name: str,
-            initial_value: float or None = None,
-            lower_bound: float or None = None,
-            upper_bound: float or None = None,
-            step: float or None = None,
-            properties: Optional[dict] = None,
-            pass_to_fem: Optional[bool] = True,
+            initial_value: float = None,
+            lower_bound: float = None,
+            upper_bound: float = None,
+            step: float = None,
+            properties: dict[str, str or float] = None,
+            pass_to_fem: bool = True,
     ):
+        # noinspection PyUnresolvedReferences
         """Adds a parameter to the optimization problem.
 
         Args:
             name (str): The name of the parameter.
-            initial_value (float or None, optional): The initial value of the parameter. Defaults to None. If None, try to get initial value from FEMInterface.
-            lower_bound (float or None, optional): The lower bound of the parameter. Defaults to None. However, this argument is required for some algorithms.
-            upper_bound (float or None, optional): The upper bound of the parameter. Defaults to None. However, this argument is required for some algorithms.
-            step (float or None, optional): The step of parameter. Defaults to None.
-            properties (dict, optional): Additional information about the parameter. Defaults to None.
+            initial_value (float, optional): The initial value of the parameter. Defaults to None. If None, try to get initial value from FEMInterface.
+            lower_bound (float, optional): The lower bound of the parameter. Defaults to None. Some optimization algorithms require this.
+            upper_bound (float or None, optional): The upper bound of the parameter. Defaults to None. Some optimization algorithms require this.
+            step (float, optional): The step of parameter. If specified, parameter is used as discrete. Defaults to None.
+            properties (dict[str, str or float], optional): Additional information about the parameter. Defaults to None.
             pass_to_fem (bool, optional): If this variable is used directly in FEM model update or not. If False, this parameter can be just used as inpt of expressions. Defaults to True.
+
         Raises:
-            ValueError: If initial_value is not specified and the value for the given name is also not specified.
+            ValueError: If initial_value is not specified and the value for the given name is also not specified in FEM.
+
+        Examples:
+
+            When adding parameter a (-1 <= a <= 1; initial value is 0), we write
+
+                >>> femopt.add_parameter('parameter_a', 0, -1, 1)  # doctest: +SKIP
+
+                Note that the ```note``` argument can be set any name in this case.
+
+            When adding discrete parameter a (-1 <= a <= 1; initial value is 0,
+            step 0.5), we write
+
+                >>> femopt.add_parameter('parameter a', 0, -1, 1, 0.5)  # doctest: +SKIP
 
         """
 
@@ -179,23 +219,73 @@ class FEMOpt:
         )
         self.opt.variables.add_parameter(prm)
 
+    @experimental_feature
     def add_expression(
             self,
             name: str,
             fun: Callable[[Any], float],
-            properties=property,
+            properties: dict[str, str or float] = None,
             kwargs: Optional[dict] = None,
             pass_to_fem=True,
     ):
+        # noinspection PyUnresolvedReferences
         """Add expression to the optimization problem.
 
+        Warnings:
+            This feature is highly experimental and
+            may change in the future.
+
         Args:
             name (str): The name of the variable.
             fun (Callable[[Any], float]): An expression function. The arguments that you want to use as input variables must be the same with ``name`` of Variable objects added by ``add_parameter()`` or ``add_expression()``. If you use other objects as argument of the function, you must specify ``kwargs``.
-            properties ([type], optional): Property names and their values of the variable. Defaults to property.
+            properties (dict[str, str or float], optional): Additional information about the parameter. Defaults to None.
             kwargs (Optional[dict], optional): Remaining arguments of ``fun``. Defaults to None.
             pass_to_fem (bool, optional): If this variable is used directly in FEM model update or not. If False, this variable can be just used as inpt of other expressions. Defaults to True.
+
+        Examples:
+
+            When adding variable a and b; a is not directly included as model
+            variables but an optimization parameter, b is not a parameter but
+            a model variable and the relationship of these 2 variables is
+            ```b = a ** 2```, we write:
+
+                >>> def calc_b(parameter_a):  # doctest: +SKIP
+                ...     return parameter_a ** 2  # doctest: +SKIP
+                ...
+                >>> femopt.add_parameter('parameter_a', 0, -1, 1, pass_to_fem=False)  # doctest: +SKIP
+                >>> femopt.add_expression('variable_b', calc_b)  # doctest: +SKIP
+
+                Notes:
+                    The argument names of function to calculate variable
+                    must match the ```name``` of the parameter.
+
+                Notes:
+                    In this case, only strings that can be used as Python variables are valid
+                    for ```name``` argument of :func:`FEMOpt.add_parameter`.
+
+            When adding variable r, theta and x, y; r, theta is an optimization
+            parameter and x, y is an intermediate variable to calculate constraint
+            function, we write
+
+                >>> def calc_x(r, theta):  # doctest: +SKIP
+                ...     return r * cos(theta)  # doctest: +SKIP
+                ...
+                >>> def calc_y(r, theta):  # doctest: +SKIP
+                ...     return r * cos(theta)  # doctest: +SKIP
+                ...
+                >>> def constraint(Femtet, opt: AbstractOptimizer):  # doctest: +SKIP
+                ...     d = opt.variables.get_variables()  # doctest: +SKIP
+                ...     x, y = d['x'], d['y']  # doctest: +SKIP
+                ...     return min(x, y)  # doctest: +SKIP
+                ...
+                >>> femopt.add_parameter('r', 0, 0, 1)  # doctest: +SKIP
+                >>> femopt.add_parameter('theta', 0, 0, 2*pi)  # doctest: +SKIP
+                >>> femopt.add_expression('x', calc_x, pass_to_fem=False)  # doctest: +SKIP
+                >>> femopt.add_expression('y', calc_y, pass_to_fem=False)  # doctest: +SKIP
+                >>> femopt.add_constraint(constraint, lower_bound=0.5, args=(femopt.opt,))  # doctest: +SKIP
+
         """
+
         exp = Expression(
             name=name,
             value=None,
@@ -214,18 +304,39 @@ class FEMOpt:
             args: tuple or None = None,
             kwargs: dict or None = None
     ):
+        # noinspection PyUnresolvedReferences
         """Adds an objective to the optimization problem.
 
         Args:
             fun (callable): The objective function.
             name (str or None, optional): The name of the objective. Defaults to None.
-            direction (str or float, optional): The optimization direction. Defaults to 'minimize'.
+            direction (str or float, optional): The optimization direction. Varid values are 'maximize', 'minimize' or a float value. Defaults to 'minimize'.
             args (tuple or None, optional): Additional arguments for the objective function. Defaults to None.
             kwargs (dict or None, optional): Additional keyword arguments for the objective function. Defaults to None.
 
         Note:
             If the FEMInterface is FemtetInterface, the 1st argument of fun should be Femtet (IPyDispatch) object.
 
+        Examples:
+
+            When add a complex objective (for example, want to dynamically set body
+            to calculate temperature and use product of the temperature and one of
+            the parameters as objective) , we write
+
+                >>> class MyClass:  # doctest: +SKIP
+                ...     def get_body_name(self):  # doctest: +SKIP
+                ...         ...  # process something and detect body name  # doctest: +SKIP
+                ...         return body_name  # doctest: +SKIP
+                ...
+                >>> def complex_objective(Femtet, opt, some_object):  # doctest: +SKIP
+                ...     body_name = some_object.get_body_name()  # dynamically get body name to calculate temperature  # doctest: +SKIP
+                ...     temp, _, _ = Femtet.Gogh.Watt.GetTemp(body_name)  # calculate temperature  # doctest: +SKIP
+                ...     some_param = opt.get_parameter()['some_param']  # get ome parameter  # doctest: +SKIP
+                ...     return temp * some_param  # calculate something and return it  # doctest: +SKIP
+                ...
+                >>> my_obj = MyClass()  # doctest: +SKIP
+                >>> femopt.add_objective(complex_objective, args=(femopt.opt, my_obj,))  # doctest: +SKIP
+
         Tip:
             If name is None, name is a string with the prefix `"obj_"` followed by a sequential number.
 
@@ -263,6 +374,7 @@ class FEMOpt:
             kwargs: dict or None = None,
             using_fem: bool = None,
     ):
+        # noinspection PyUnresolvedReferences
         """Adds a constraint to the optimization problem.
 
         Args:
@@ -275,6 +387,36 @@ class FEMOpt:
             kwargs (dict): Additional arguments for the constraint function. Defaults to None.
             using_fem (bool, optional): Using FEM or not in the constraint function. It may make the processing time in strict constraints in BoTorchSampler. Defaults to None. If None, PyFemtet checks the access to Femtet and estimate using Femtet or not automatically.
 
+        Warnings:
+
+            When ```strict``` == True and using OptunaOptimizer along with :class:`PoFBoTorchSampler`,
+            PyFemtet will solve an optimization subproblem to propose new variables.
+            During this process, the constraint function ```fun``` will be executed at each
+            iteration of the subproblem, which may include time-consuming operations such
+            as retrieving 3D model information via FEMInterface.
+            As a result, it may not be feasible to complete the overall optimization within
+            a realistic timeframe.
+
+            Examples:
+                For example, in a case where the bottom area of the model is constrained,
+                the following approach may require a very long time.
+
+                    >>> def bottom_area(Femtet, opt):  # doctest: +SKIP
+                    ...     w = Femtet.GetVariableValue('width')  # doctest: +SKIP
+                    ...     d = Femtet.GetVariableValue('depth')  # doctest: +SKIP
+                    ...     return w * d  # doctest: +SKIP
+                    ...
+                    >>> femopt.add_constraint(constraint, lower_bound=5)  # doctest: +SKIP
+
+                Instead, please do the following.
+
+                    >>> def bottom_area(_, opt):  # Not to access the 1st argument.  # doctest: +SKIP
+                    ...     params = opt.get_parameter()  # doctest: +SKIP
+                    ...     w, d = params['width'], params['depth']  # doctest: +SKIP
+                    ...     return w * d  # doctest: +SKIP
+                    ...
+                    >>> femopt.add_constraint(constraint, lower_bound=5, args=(femopt.opt,))  # doctest: +SKIP
+
         Note:
             If the FEMInterface is FemtetInterface, the 1st argument of fun should be Femtet (IPyDispatch) object.
 
@@ -330,22 +472,32 @@ class FEMOpt:
         self.opt.constraints[name] = Constraint(fun, name, lower_bound, upper_bound, strict, args, kwargs, using_fem)
 
     def get_parameter(self, format='dict'):
-        raise DeprecationWarning('FEMOpt.get_parameter() was deprecated. Use Femopt.opt.get_parameter() instead.')
+        """Deprecated method.
+
+        Planed to remove in future version. Use FEMOpt.opt.get_parameter() instead.
+        """
+        raise DeprecationWarning('FEMOpt.get_parameter() was deprecated. Use FEMOpt.opt.get_parameter() instead.')
 
     def set_monitor_host(self, host=None, port=None):
-        """Sets up the monitor server with the specified host and port.
+        """Sets the host IP address and the port of the process monitor.
 
         Args:
-            host (str): The hostname or IP address of the monitor server.
-            port (int or None, optional): The port number of the monitor server. If None, ``8080`` will be used. Defaults to None.
+            host (str):
+                The hostname or IP address of the monitor server.
+            port (int, optional):
+                The port number of the monitor server.
+                If None, ``8080`` will be used.
+                Defaults to None.
 
         Tip:
-            Specifying host ``0.0.0.0`` allows viewing monitor from all computers on the local network.
+            Specifying host ``0.0.0.0`` allows viewing monitor
+            from all computers on the local network.
 
-            However, please note that in this case,
-            it will be visible to all users on the local network.
+            If no hostname is specified, the monitor server
+            will be hosted on ``localhost``.
 
-            If no hostname is specified, the monitor server will be hosted on ``localhost``.
+            We can access process monitor by accessing
+            ```localhost:8080``` on our browser by default.
 
         """
         self.monitor_server_kwargs = dict(
@@ -355,33 +507,57 @@ class FEMOpt:
 
     def optimize(
             self,
-            n_trials=None,
-            n_parallel=1,
-            timeout=None,
-            wait_setup=True,
-            confirm_before_exit=True,
+            n_trials: int = None,
+            n_parallel: int = 1,
+            timeout: float = None,
+            wait_setup: bool = True,
+            confirm_before_exit: bool = True,
     ):
         """Runs the main optimization process.
 
         Args:
-            n_trials (int or None, optional): The number of trials. Defaults to None.
-            n_parallel (int, optional): The number of parallel processes. Defaults to 1.
-            timeout (float or None, optional): The maximum amount of time in seconds that each trial can run. Defaults to None.
-            wait_setup (bool, optional): Wait for all workers launching FEM system. Defaults to True.
-            confirm_before_exit (bool, optional): Insert stop before exit to continue to show process monitor.
+            n_trials (int, optional):
+                The number of trials.
+                Defaults to None.
+            n_parallel (int, optional):
+                The number of parallel processes.
+                Defaults to 1.
+                Note that even if this argument is 1,
+                :class:`FEMOpt` makes some child processes
+                to run process monitor, status monitor, etc.
+            timeout (float, optional):
+                The maximum amount of time in seconds
+                that each trial can run.
+                Defaults to None.
+            wait_setup (bool, optional):
+                Wait for all workers launching FEM system.
+                Defaults to True.
+            confirm_before_exit (bool, optional):
+                Insert stop before exit to continue to
+                show process monitor.
 
         Tip:
-            If set_monitor_host() is not executed, a local server for monitoring will be started at localhost:8080.
+            If set_monitor_host() is not executed,
+            a local server for monitoring will be
+            started at localhost:8080.
+
+            See Also:
+                :func:`FEMOpt.set_monitor_host`
 
         Note:
-            If ``n_trials`` and ``timeout`` are both None, it runs forever until interrupting by the user.
+            If ``n_trials`` and ``timeout`` are both None,
+            it runs forever until interrupting by the user.
 
         Note:
-            If ``n_parallel`` >= 2, depending on the end timing, ``n_trials`` may be exceeded by up to ``n_parallel-1`` times.
+            If ``n_parallel`` >= 2, depending on the end timing,
+            ``n_trials`` may be exceeded by up to ``n_parallel-1`` times.
 
         Warning:
-            If ``n_parallel`` >= 2 and ``fem`` is a subclass of ``FemtetInterface``, the ``strictly_pid_specify`` of subprocess is set to ``False``.
-            So **it is recommended to close all other Femtet processes before running.**
+            If ``n_parallel`` >= 2 and ``fem`` is a subclass of
+            ``FemtetInterface``, the ``strictly_pid_specify`` of
+            subprocess is set to ``False``.
+            So **it is recommended to close all other Femtet processes
+            before running.**
 
         """
 
@@ -451,14 +627,21 @@ class FEMOpt:
 
         else:
             # ローカルクラスターを構築
-            logger.info('Launching single machine cluster. This may take tens of seconds.')
+            logger.info('Launching single machine cluster... This may take tens of seconds.')
+
+            # Fixed:
+            #   Nanny の管理機能は必要ないが、Python API では worker_class を Worker にすると
+            #   processes 引数が無視されて Thread worker が立てられる。
+            #   これは CLI の --no-nanny オプションも同様らしい。
+
+            # クラスターの構築
             cluster = LocalCluster(
                 processes=True,
-                n_workers=n_parallel,  # n_parallel = n_parallel - 1 + 1; main 分減らし、monitor 分増やす
+                n_workers=n_parallel,
                 threads_per_worker=1,
-                worker_class=Worker,
             )
             logger.info('LocalCluster launched successfully.')
+
             self.client = Client(cluster, direct_to_workers=False)
             self.scheduler_address = self.client.scheduler.address
             logger.info('Client launched successfully.')
@@ -483,6 +666,7 @@ class FEMOpt:
                         model_name=self.fem.model_name
                     )
                 )
+
                 # Femtet の parametric 設定を目的関数に用いるかどうか
                 if self.fem.parametric_output_indexes_use_as_objective is not None:
                     from pyfemtet.opt.interface._femtet_parametric import add_parametric_results_as_objectives
@@ -493,8 +677,14 @@ class FEMOpt:
                         indexes,
                         directions,
                     )
+
+                # Femtet の confirm_before_exit のセット
+                self.fem.confirm_before_exit = confirm_before_exit
+                self.fem.kwargs['confirm_before_exit'] = confirm_before_exit
+
                 logger.info('Femtet loaded successfully.')
 
+
             # actor の設定
             self.status = OptimizationStatus(_client)
             self.worker_status_list = [OptimizationStatus(_client, name) for name in worker_addresses]  # tqdm 検討
@@ -506,10 +696,12 @@ class FEMOpt:
                 list(self.opt.constraints.keys()),
                 _client,
                 metadata,
+                self._hv_reference
             )
             logger.info('Status Actor initialized successfully.')
 
             # launch monitor
+            # noinspection PyTypeChecker
             self.monitor_process_future = _client.submit(
                 # func
                 _start_monitor_server,
@@ -634,6 +826,11 @@ class FEMOpt:
 
     @staticmethod
     def terminate_all():
+        """Deprecated method. We plan to remove this in future version.
+
+        In current version, the termination processes are
+        automatically execute in the last of :func:`FEMOpt.optimize`.
+        """
         warnings.warn(
             "terminate_all() is deprecated and will be removed in a future version. "
             "In current and later versions, the equivalent of terminate_all() will be executed when optimize() finishes. "