pyfemtet 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

pyfemtet/opt/_femopt.py

@@ -17,7 +17,7 @@ from dask.distributed import LocalCluster, Client, Worker
 # 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,8 +28,9 @@ 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
 
 
 def add_worker(client, worker_name):
@@ -54,27 +55,47 @@ def add_worker(client, worker_name):
     client.wait_for_workers(n_workers=current_n_workers + 1)
 
 
-
 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
 
     """
 
@@ -133,25 +154,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 +215,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 +300,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 +370,7 @@ class FEMOpt:
             kwargs: dict or None = None,
             using_fem: bool = None,
     ):
+        # noinspection PyUnresolvedReferences
         """Adds a constraint to the optimization problem.
 
         Args:
@@ -275,6 +383,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 BoTorchSampler,
+            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):  # 第一引数 Femtet にはアクセスしないようにします。  # 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 +468,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 +503,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.**
 
         """
 
@@ -510,6 +682,7 @@ class FEMOpt:
             logger.info('Status Actor initialized successfully.')
 
             # launch monitor
+            # noinspection PyTypeChecker
             self.monitor_process_future = _client.submit(
                 # func
                 _start_monitor_server,
@@ -634,6 +807,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. "

pyfemtet/opt/_femopt_core.py

@@ -8,13 +8,20 @@ import inspect
 import ast
 import csv
 import ctypes
+from packaging import version
 
 # 3rd-party
 import numpy as np
 import pandas as pd
 from scipy.stats.qmc import LatinHypercube
 import optuna
-from optuna._hypervolume import WFG
+if version.parse(optuna.version.__version__) < version.parse('4.0.0'):
+    from optuna._hypervolume import WFG
+    wfg = WFG()
+    compute_hypervolume = wfg.compute
+else:
+    from optuna._hypervolume import wfg
+    compute_hypervolume = wfg.compute_hypervolume
 from dask.distributed import Lock, get_client
 
 # win32com
@@ -22,7 +29,7 @@ from win32com.client import constants, Constants
 
 # pyfemtet relative
 from pyfemtet.opt.interface import FEMInterface, FemtetInterface
-from pyfemtet.message import encoding, Msg
+from pyfemtet._message import encoding, Msg
 
 # logger
 import logging
@@ -708,20 +715,27 @@ class History:
 
     def _calc_non_domi(self, objectives, df):
 
+        # feasible のもののみ取り出してくる
+        idx = df['feasible'].values
+        pdf = df[idx]
+
         # 目的関数の履歴を取り出してくる
-        solution_set = df[self.obj_names]
+        solution_set = pdf[self.obj_names]
 
         # 最小化問題の座標空間に変換する
         for obj_column, (_, objective) in zip(self.obj_names, objectives.items()):
             solution_set.loc[:, obj_column] = solution_set[obj_column].map(objective.convert)
 
         # 非劣解の計算
-        non_domi = []
+        non_domi: list[bool] = []
         for i, row in solution_set.iterrows():
             non_domi.append((row > solution_set).product(axis=1).sum(axis=0) == 0)
 
-        # 非劣解の登録
-        df['non_domi'] = non_domi
+        # feasible も infeasible も一旦劣解にする
+        df['non_domi'] = False
+
+        # feasible のものに non_domi の評価結果を代入する
+        df.loc[idx, 'non_domi'] = non_domi
 
     def _calc_hypervolume(self, objectives, df):
 
@@ -753,10 +767,9 @@ class History:
         reference_point = r * (maximum - minimum) + minimum
 
         #### hv 履歴の計算
-        wfg = WFG()
         hvs = []
         for i in range(n):
-            hv = wfg.compute(pareto_set[:i], reference_point)
+            hv = compute_hypervolume(pareto_set[:i], reference_point)
             if np.isnan(hv):
                 hv = 0
             hvs.append(hv)

pyfemtet/opt/_test_utils/record_history.py

@@ -7,7 +7,7 @@ import numpy as np
 import pandas as pd
 
 from pyfemtet.opt import FEMOpt
-from pyfemtet.message import encoding as ENCODING
+from pyfemtet._message import encoding as ENCODING
 
 
 def find_latest_csv(dir_path=None):

pyfemtet/opt/interface/__init__.py

@@ -11,5 +11,4 @@ __all__ = [
     'FemtetInterface',
     'FemtetWithNXInterface',
     'FemtetWithSolidworksInterface',
-    'logger',
 ]

pyfemtet/opt/interface/_base.py

@@ -68,15 +68,15 @@ class FEMInterface(ABC):
         """Preprocessing after launching a dask worker and before run optimization (if implemented in concrete class)."""
         pass
 
-    def postprocess_func(self, trial: int, *args, dask_scheduler=None, **kwargs):
+    def _postprocess_func(self, trial: int, *args, dask_scheduler=None, **kwargs):
         pass
 
-    def create_postprocess_args(self):
+    def _create_postprocess_args(self):
         pass
 
 
 class NoFEM(FEMInterface):
-    """Interface with no FEM for debug."""
+    """Dummy interface without FEM. Intended for debugging purposes."""
 
     def update(self, parameters: pd.DataFrame) -> None:
         pass