:py:mod:`cotengra.scoring` ========================== .. py:module:: cotengra.scoring .. autoapi-nested-parse:: Objects for defining and customizing the target cost of a contraction. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: cotengra.scoring.Objective cotengra.scoring.ExactObjective cotengra.scoring.FlopsObjective cotengra.scoring.WriteObjective cotengra.scoring.SizeObjective cotengra.scoring.ComboObjective cotengra.scoring.LimitObjective cotengra.scoring.CompressedStatsTracker cotengra.scoring.CompressedStatsTrackerSize cotengra.scoring.CompressedStatsTrackerPeak cotengra.scoring.CompressedStatsTrackerWrite cotengra.scoring.CompressedStatsTrackerFlops cotengra.scoring.CompressedStatsTrackerCombo cotengra.scoring.CompressedObjective cotengra.scoring.CompressedSizeObjective cotengra.scoring.CompressedPeakObjective cotengra.scoring.CompressedWriteObjective cotengra.scoring.CompressedFlopsObjective cotengra.scoring.CompressedComboObjective cotengra.scoring.MultiObjective cotengra.scoring.MultiObjectiveDense cotengra.scoring.MultiObjectiveUniform cotengra.scoring.MultiObjectiveLinear Functions ~~~~~~~~~ .. autoapisummary:: cotengra.scoring.ensure_basic_quantities_are_computed cotengra.scoring.parse_minimize cotengra.scoring._get_score_fn_str_cached cotengra.scoring.get_score_fn cotengra.scoring.expected_coupons Attributes ~~~~~~~~~~ .. autoapisummary:: cotengra.scoring.DEFAULT_COMBO_FACTOR cotengra.scoring.score_matcher .. py:data:: DEFAULT_COMBO_FACTOR :value: 64 .. py:class:: Objective Base mixin class for all objectives. .. py:attribute:: __slots__ :value: () .. py:method:: __call__(trial) :abstractmethod: The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:method:: __repr__() Return repr(self). .. py:method:: __hash__() Return hash(self). .. py:function:: ensure_basic_quantities_are_computed(trial) .. py:class:: ExactObjective Bases: :py:obj:`Objective` Mixin class for all exact objectives. .. py:method:: cost_local_tree_node(tree, node) :abstractmethod: The cost of a single ``node`` in ``tree``, according to this objective. Used for subtree reconfiguration. .. py:method:: score_local(**kwargs) :abstractmethod: The score to give a single contraction, according to the given ``kwargs``. Used in ``simulated_anneal``. .. py:method:: score_slice_index(costs, ix) :abstractmethod: The score to give possibly slicing ``ix``, according to the given ``costs``. Used in the ``SliceFinder`` optimization. .. py:method:: get_dynamic_programming_minimize() :abstractmethod: Get the argument for optimal optimization, used in subtree reconfiguration. .. py:class:: FlopsObjective(secondary_weight=0.001) Bases: :py:obj:`ExactObjective` Objective that scores based on estimated floating point operations. :param secondary_weight: Weighting factor for secondary objectives (max size and total write). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('secondary_weight',) .. py:method:: cost_local_tree_node(tree, node) The cost of a single ``node`` in ``tree``, according to this objective. Used for subtree reconfiguration. .. py:method:: score_local(**kwargs) The score to give a single contraction, according to the given ``kwargs``. Used in ``simulated_anneal``. .. py:method:: score_slice_index(costs, ix) The score to give possibly slicing ``ix``, according to the given ``costs``. Used in the ``SliceFinder`` optimization. .. py:method:: get_dynamic_programming_minimize() Get the argument for optimal optimization, used in subtree reconfiguration. .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: WriteObjective(secondary_weight=0.001) Bases: :py:obj:`ExactObjective` Objective that scores based on estimated total write, i.e. the sum of sizes of all intermediates. This is relevant for completely memory-bound contractions, and also for back-propagation. :param secondary_weight: Weighting factor for secondary objectives (max size and total flops). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('secondary_weight',) .. py:method:: cost_local_tree_node(tree, node) The cost of a single ``node`` in ``tree``, according to this objective. Used for subtree reconfiguration. .. py:method:: score_local(**kwargs) The score to give a single contraction, according to the given ``kwargs``. Used in ``simulated_anneal``. .. py:method:: score_slice_index(costs, ix) The score to give possibly slicing ``ix``, according to the given ``costs``. Used in the ``SliceFinder`` optimization. .. py:method:: get_dynamic_programming_minimize() Get the argument for optimal optimization, used in subtree reconfiguration. .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: SizeObjective(secondary_weight=0.001) Bases: :py:obj:`ExactObjective` Objective that scores based on maximum intermediate size. :param secondary_weight: Weighting factor for secondary objectives (total flops and total write). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('secondary_weight',) .. py:method:: cost_local_tree_node(tree, node) The cost of a single ``node`` in ``tree``, according to this objective. Used for subtree reconfiguration. .. py:method:: score_local(**kwargs) The score to give a single contraction, according to the given ``kwargs``. Used in ``simulated_anneal``. .. py:method:: score_slice_index(costs, ix) The score to give possibly slicing ``ix``, according to the given ``costs``. Used in the ``SliceFinder`` optimization. .. py:method:: get_dynamic_programming_minimize() Get the argument for optimal optimization, used in subtree reconfiguration. .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: ComboObjective(factor=DEFAULT_COMBO_FACTOR) Bases: :py:obj:`ExactObjective` Objective that scores based on a combination of estimated floating point operations and total write, according to: .. math:: \log_2(\text{flops} + \alpha \times \text{write}) Where alpha is the ``factor`` parameter of this objective, that describes approximately how much slower write speeds are. :param factor: Weighting factor for total write. Default is 64. :type factor: float, optional .. py:attribute:: __slots__ :value: ('factor',) .. py:method:: cost_local_tree_node(tree, node) The cost of a single ``node`` in ``tree``, according to this objective. Used for subtree reconfiguration. .. py:method:: score_local(**kwargs) The score to give a single contraction, according to the given ``kwargs``. Used in ``simulated_anneal``. .. py:method:: score_slice_index(costs, ix) The score to give possibly slicing ``ix``, according to the given ``costs``. Used in the ``SliceFinder`` optimization. .. py:method:: get_dynamic_programming_minimize() Get the argument for optimal optimization, used in subtree reconfiguration. .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: LimitObjective(factor=DEFAULT_COMBO_FACTOR) Bases: :py:obj:`ExactObjective` Objective that scores based on a maximum of either estimated floating point operations or the total write, weighted by some factor: .. math:: \sum_{c} max(\text{flops}_i, \alpha \times \text{write}_i) For each contraction $i$. Where alpha is the ``factor`` parameter of this objective, that describes approximately how much slower write speeds are. This assumes that one or the other is the limiting factor. :param factor: Weighting factor for total write. Default is 64. :type factor: float, optional .. py:method:: cost_local_tree_node(tree, node) The cost of a single ``node`` in ``tree``, according to this objective. Used for subtree reconfiguration. .. py:method:: score_local(**kwargs) The score to give a single contraction, according to the given ``kwargs``. Used in ``simulated_anneal``. .. py:method:: score_slice_index(costs, ix) The score to give possibly slicing ``ix``, according to the given ``costs``. Used in the ``SliceFinder`` optimization. .. py:method:: get_dynamic_programming_minimize() Get the argument for optimal optimization, used in subtree reconfiguration. .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: CompressedStatsTracker(hg, chi) .. py:property:: combo_score .. py:property:: score :abstractmethod: .. py:attribute:: __slots__ :value: ('chi', 'flops', 'max_size', 'peak_size', 'write', 'total_size', 'total_size_post_contract',... .. py:method:: copy() .. py:method:: update_pre_step() .. py:method:: update_pre_compress(hg, *nodes) .. py:method:: update_post_compress(hg, *nodes) .. py:method:: update_pre_contract(hg, i, j) .. py:method:: update_post_contract(hg, ij) .. py:method:: update_post_step() .. py:method:: update_score(other) .. py:method:: describe(join=' ') .. py:method:: __repr__() Return repr(self). .. py:class:: CompressedStatsTrackerSize(hg, chi, secondary_weight=0.001) Bases: :py:obj:`CompressedStatsTracker` .. py:property:: score .. py:attribute:: __slots__ .. py:class:: CompressedStatsTrackerPeak(hg, chi, secondary_weight=0.001) Bases: :py:obj:`CompressedStatsTracker` .. py:property:: score .. py:attribute:: __slots__ .. py:class:: CompressedStatsTrackerWrite(hg, chi, secondary_weight=0.001) Bases: :py:obj:`CompressedStatsTracker` .. py:property:: score .. py:attribute:: __slots__ .. py:class:: CompressedStatsTrackerFlops(hg, chi, secondary_weight=0.001) Bases: :py:obj:`CompressedStatsTracker` .. py:property:: score .. py:attribute:: __slots__ .. py:class:: CompressedStatsTrackerCombo(hg, chi, factor=DEFAULT_COMBO_FACTOR) Bases: :py:obj:`CompressedStatsTracker` .. py:property:: score .. py:attribute:: __slots__ .. py:class:: CompressedObjective(chi='auto', compress_late=False) Bases: :py:obj:`Objective` Mixin for objectives that score based on a compressed contraction. .. py:method:: get_compressed_stats_tracker(hg) :abstractmethod: Return a tracker for compressed contraction stats. :param hg: The hypergraph to track stats for. :type hg: Hypergraph :returns: The tracker. :rtype: CompressedStatsTracker .. py:method:: compute_compressed_stats(trial) .. py:class:: CompressedSizeObjective(chi='auto', compress_late=False, secondary_weight=0.001) Bases: :py:obj:`CompressedObjective` Objective that scores based on the maximum size intermediate tensor during a compressed contraction with maximum bond dimension ``chi``. :param chi: Maximum bond dimension to use for the compressed contraction. Default is ``"auto"``, which will use the square of the maximum size of any input tensor dimension. :type chi: int, optional :param compress_late: Whether to compress the neighboring tensors just after (early) or just before (late) contracting tensors. Default is False, i.e. early. :type compress_late: bool, optional :param secondary_weight: Weighting factor for secondary objectives (flops and write). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('chi', 'compress_late', 'secondary_weight') .. py:method:: get_compressed_stats_tracker(hg) Return a tracker for compressed contraction stats. :param hg: The hypergraph to track stats for. :type hg: Hypergraph :returns: The tracker. :rtype: CompressedStatsTracker .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: CompressedPeakObjective(chi='auto', compress_late=False, secondary_weight=0.001) Bases: :py:obj:`CompressedObjective` Objective that scores based on the peak total concurrent size of intermediate tensors during a compressed contraction with maximum bond dimension ``chi``. :param chi: Maximum bond dimension to use for the compressed contraction. Default is ``"auto"``, which will use the square of the maximum size of any input tensor dimension. :type chi: int, optional :param compress_late: Whether to compress the neighboring tensors just after (early) or just before (late) contracting tensors. Default is False, i.e. early. :type compress_late: bool, optional :param secondary_weight: Weighting factor for secondary objectives (flops and write). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('chi', 'compress_late', 'secondary_weight') .. py:method:: get_compressed_stats_tracker(hg) Return a tracker for compressed contraction stats. :param hg: The hypergraph to track stats for. :type hg: Hypergraph :returns: The tracker. :rtype: CompressedStatsTracker .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: CompressedWriteObjective(chi='auto', compress_late=False, secondary_weight=0.001) Bases: :py:obj:`CompressedObjective` Objective that scores based on the total cumulative size of intermediate tensors during a compressed contraction with maximum bond dimension ``chi``. :param chi: Maximum bond dimension to use for the compressed contraction. Default is ``"auto"``, which will use the square of the maximum size of any input tensor dimension. :type chi: int, optional :param compress_late: Whether to compress the neighboring tensors just after (early) or just before (late) contracting tensors. Default is False, i.e. early. :type compress_late: bool, optional :param secondary_weight: Weighting factor for secondary objectives (flops and peak size). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('chi', 'compress_late', 'secondary_weight') .. py:method:: get_compressed_stats_tracker(hg) Return a tracker for compressed contraction stats. :param hg: The hypergraph to track stats for. :type hg: Hypergraph :returns: The tracker. :rtype: CompressedStatsTracker .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: CompressedFlopsObjective(chi='auto', compress_late=False, secondary_weight=0.001) Bases: :py:obj:`CompressedObjective` Objective that scores based on the total contraction flops intermediate tensors during a compressed contraction with maximum bond dimension ``chi``. :param chi: Maximum bond dimension to use for the compressed contraction. Default is ``"auto"``, which will use the square of the maximum size of any input tensor dimension. :type chi: int, optional :param compress_late: Whether to compress the neighboring tensors just after (early) or just before (late) contracting tensors. Default is False, i.e. early. :type compress_late: bool, optional :param secondary_weight: Weighting factor for secondary objectives (write and peak size). Default is 1e-3. :type secondary_weight: float, optional .. py:attribute:: __slots__ :value: ('chi', 'compress_late', 'secondary_weight') .. py:method:: get_compressed_stats_tracker(hg) Return a tracker for compressed contraction stats. :param hg: The hypergraph to track stats for. :type hg: Hypergraph :returns: The tracker. :rtype: CompressedStatsTracker .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:class:: CompressedComboObjective(chi='auto', compress_late=False, factor=DEFAULT_COMBO_FACTOR) Bases: :py:obj:`CompressedObjective` Mixin for objectives that score based on a compressed contraction. .. py:attribute:: __slots__ :value: ('chi', 'compress_late', 'factor') .. py:method:: get_compressed_stats_tracker(hg) Return a tracker for compressed contraction stats. :param hg: The hypergraph to track stats for. :type hg: Hypergraph :returns: The tracker. :rtype: CompressedStatsTracker .. py:method:: __call__(trial) The core method that takes a ``trial`` generated by a contraction path driver and scores it to report to a hyper-optimizer. It might also update the parameters in the trial to reflect the desired cost. .. py:data:: score_matcher .. py:function:: parse_minimize(minimize) .. py:function:: _get_score_fn_str_cached(minimize) .. py:function:: get_score_fn(minimize) .. py:class:: MultiObjective(num_configs) Bases: :py:obj:`Objective` Base mixin class for all objectives. .. py:attribute:: __slots__ :value: ('num_configs',) .. py:method:: compute_mult(dims) :abstractmethod: .. py:method:: estimate_node_mult(tree, node) .. py:method:: estimate_node_cache_mult(tree, node, sliced_ind_ordering) .. py:class:: MultiObjectiveDense(num_configs) Bases: :py:obj:`MultiObjective` Number of intermediate configurations is expected to scale as if all configurations are present. .. py:attribute:: __slots__ :value: ('num_configs',) .. py:method:: compute_mult(dims) .. py:function:: expected_coupons(num_sub, num_total) If we draw a random 'coupon` which can take `num_sub` different values `num_total` times, how many unique coupons will we expect? .. py:class:: MultiObjectiveUniform(num_configs) Bases: :py:obj:`MultiObjective` Number of intermediate configurations is expected to scale as if all configurations are randomly draw from a uniform distribution. .. py:attribute:: __slots__ :value: ('num_configs',) .. py:method:: compute_mult(dims) .. py:class:: MultiObjectiveLinear(num_configs, coeff=1) Bases: :py:obj:`MultiObjective` Number of intermediate configurations is expected to scale linearly with respect to number of variable indices (e.g. VMC like 'locally connected' configurations). .. py:attribute:: __slots__ :value: ('num_configs', 'coeff') .. py:method:: compute_mult(dims)