Scoped config
A set_*! function replaces the global default of one setting of the package in one atomic step. A with_* function changes the setting for the duration of one call, and restores it after. The tasks that the call starts see the change too. The functions are public and not exported, so call them as PortfolioOptimisers.set_resource_limits!.
Base.getindex — Method
getindex(cfg::ScopedConfig)Read the active value of a ScopedConfig. Inside a with_* block it is the innermost task-scoped override. In other code it is the global default, which the function reads atomically.
Algorithm
- Read
cfg.scoped[], the innermost task-scoped override. It isnothingoutside everywith_*block. - When step 1 gives
nothing, readcfg.defaultatomically.
Returns
x::T: The active value of the configuration.
Related
PortfolioOptimisers.set_resource_limits! — Function
set_resource_limits!(; max_n_sim::Integer, max_n_subsets::Integer,
max_frontier::Integer, max_bins::Integer,
max_hop_count::Integer, max_search_grid::Integer,
max_ep_grid::Integer)Set the global default of the resource caps of RESOURCE_LIMITS.
Raise the caps for a large run that a program configured, on a machine with enough memory for it. Lower them to accept less untrusted input. A keyword that the caller omits keeps its current default. The store is atomic, as ScopedConfig states. For a temporary, task-scoped override, usewith_resource_limits.
Algorithm
- Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
- Build a
ResourceLimitsfrom the seven keywords. The validation below runs in that constructor. - Store it as the global default of
RESOURCE_LIMITSthroughset_default!.
Arguments
max_n_sim::Integer: The maximumn_simthat the uncertainty-set estimators accept.max_n_subsets::Integer: The maximumn_subsetsthat the subset-resampling estimators accept.max_frontier::Integer: The maximumNthat oneFrontieraccepts, and the maximum number of sweep points over all swept bounds.max_bins::Integer: The maximumbinsthat the mutual-information estimators accept.max_hop_count::Integer: The maximumnthatHopCountaccepts, as a stated value or as the value that a rule resolves.max_search_grid::Integer: The maximum number of candidates in the grid of a search cross-validation.max_ep_grid::Integer: The maximumKthat the grid formulations of the entropic and relativistic value-at-risk views accept.
Validation
- Every cap is positive.
ResourceLimitschecks it.
Returns
lims::ResourceLimits: The new global default.
Related
PortfolioOptimisers.with_resource_limits — Function
with_resource_limits(f; max_n_sim::Integer = RESOURCE_LIMITS[].max_n_sim,
max_n_subsets::Integer = RESOURCE_LIMITS[].max_n_subsets,
max_frontier::Integer = RESOURCE_LIMITS[].max_frontier,
max_bins::Integer = RESOURCE_LIMITS[].max_bins,
max_hop_count::Integer = RESOURCE_LIMITS[].max_hop_count,
max_search_grid::Integer = RESOURCE_LIMITS[].max_search_grid,
max_ep_grid::Integer = RESOURCE_LIMITS[].max_ep_grid)Run f() with an override of the resource caps of RESOURCE_LIMITS for the dynamic extent of the call. The previous caps come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.
Use it to raise a cap for one large run, while other concurrent work keeps its caps. The library reads a cap where it resolves the value. It reads the caps on n_sim, N, bins and K when the caller constructs the estimator. It reads the cap on n_subsets when the optimisation resolves its schedule, which can be a TimeDependent. Put this call around the constructor call for the first four caps, and around the optimise call for n_subsets.
Algorithm
- Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
- Build a
ResourceLimitsfrom the seven keywords. The validation below runs in that constructor. - Run
f()withRESOURCE_LIMITSbound to that value throughwith_config.
Arguments
f: The zero-argument function to run under the override.max_n_sim::Integer: The maximumn_simthat the uncertainty-set estimators accept.max_n_subsets::Integer: The maximumn_subsetsthat the subset-resampling estimators accept.max_frontier::Integer: The maximumNthat oneFrontieraccepts, and the maximum number of sweep points over all swept bounds.max_bins::Integer: The maximumbinsthat the mutual-information estimators accept.max_hop_count::Integer: The maximumnthatHopCountaccepts, as a stated value or as the value that a rule resolves.max_search_grid::Integer: The maximum number of candidates in the grid of a search cross-validation.max_ep_grid::Integer: The maximumKthat the grid formulations of the entropic and relativistic value-at-risk views accept.
Validation
- Every cap is positive.
ResourceLimitschecks it.
Returns
- The value that
f()returns.
Related
PortfolioOptimisers.set_compact_show! — Function
set_compact_show!(x::Bool)
set_compact_show!(n::Integer)Configure whether @define_pretty_show collapses large nested structs.
set_compact_show!(false): Turn the collapse off, so that each struct prints in full.set_compact_show!(true): Turn the collapse on, with a budget that the size of the terminal sets.set_compact_show!(n): Turn the collapse on, with a fixed line budgetn.
The collapse applies only to output with a limited height, where get(io, :limit, false) is true. The interactive REPL is such output. Output with no limit, such as string, repr and a write to a file, always prints in full. The documentation build turns the collapse off, so that the rendered docs show each field. A single call can override the global setting with the :po_compact IO property, which takes false, true or an Int.
The function sets the global default in one atomic store, as ScopedConfig states. For a temporary, task-scoped override, use with_compact_show.
Algorithm
- Widen an
Integerargument toInt. The two methods then store one of the two members of the stored union, and never a third integer type. ABooldoes not change. - Store the value as the global default of
COMPACT_SHOWthroughset_default!.
Arguments
x::Bool:falseturns the collapse off.trueturns it on, with the automatic budget.n::Integer: The fixed line budget, which the function stores as anInt.
Returns
x::Union{Bool, Int}: The stored setting.
Related
PortfolioOptimisers.with_compact_show — Function
with_compact_show(f, x::Bool)
with_compact_show(f, n::Integer)Run f() with the collapse setting of COMPACT_SHOW set to x or n for the dynamic extent of the call. The previous setting comes back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change.
Algorithm
- Widen an
Integerargument toInt, asset_compact_show!does. ABooldoes not change. - Run
f()withCOMPACT_SHOWbound to that value throughwith_config.
Arguments
f: The zero-argument function to run under the override.x::Bool:falseturns the collapse off.trueturns it on, with the automatic budget.n::Integer: The fixed line budget, which the function stores as anInt.
Returns
- The value that
f()returns.
Related
PortfolioOptimisers.set_show_nothing_fields! — Function
set_show_nothing_fields!(x::Bool)
set_show_nothing_fields!(name::Symbol, x::Union{Nothing, Bool})Configure whether @define_pretty_show renders a field that holds nothing.
set_show_nothing_fields!(false): Hide anothingfield, for every type that no per-name entry names. This is the package default.set_show_nothing_fields!(true): Print anothingfield, for every type that no per-name entry names.set_show_nothing_fields!(:SimpleVariance, false): Hide thenothingfields of every type with the nameSimpleVariance, whatever the global switch holds.set_show_nothing_fields!(:SimpleVariance, true): Print every declared field of every type with the nameSimpleVariance, also a field that its ownshow_fieldsmethod hides.set_show_nothing_fields!(:SimpleVariance, nothing): Remove the per-name entry, so that the type again obeys the global switch and its ownshow_fieldsmethod.
The per-name form takes a name and not a type, because the preferences that load at start are TOML, and TOML holds no types. The name is the name of the type without its module, so two types with one name in two modules share one entry. The function accepts a name that matches no type, and the entry then has no effect. A type outside the package can also print through @define_pretty_show, so the function cannot refuse an unknown name.
The function sets the global default in one atomic store, as ScopedConfig states. For a temporary, task-scoped override, use with_show_nothing_fields.
Algorithm
- Read the current global default of
SHOW_NOTHING_FIELDSatomically. The function does not read a scoped override, so the call changes the global default alone. - Build the new
ShowNothingFields. The one-argument form keeps the per-name table and replaces the global switch. The two-argument form keeps the global switch, and copies the table with one entry set or removed. - Store it as the global default through
set_default!.
Arguments
x::Bool:falsehides anothingfield, andtrueprints it.name::Symbol: The name of a type, without its module.x::Union{Nothing, Bool}: In the per-name form, the entry to set, ornothingto remove the entry.
Returns
cfg::ShowNothingFields: The new global default.
Related
PortfolioOptimisers.with_show_nothing_fields — Function
with_show_nothing_fields(f, x::Bool)
with_show_nothing_fields(f, name::Symbol, x::Union{Nothing, Bool})Run f() with an override of the SHOW_NOTHING_FIELDS setting for the dynamic extent of the call. The previous setting comes back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. The part of the setting that the call does not name comes from the active value, so a nested override adds to the override around it.
Algorithm
- Read the active value of
SHOW_NOTHING_FIELDS. A nested override then starts from the override around it, and not from the global default. - Build the override as
set_show_nothing_fields!does. The one-argument form replaces the global switch and keeps the per-name table. The two-argument form keeps the global switch, and copies the table with one entry set or removed. - Run
f()withSHOW_NOTHING_FIELDSbound to that value throughwith_config.
Arguments
f: The zero-argument function to run under the override.x::Bool:falsehides anothingfield, andtrueprints it.name::Symbol: The name of a type, without its module.x::Union{Nothing, Bool}: In the per-name form, the entry to set, ornothingto remove the entry.
Returns
- The value that
f()returns.
Related
PortfolioOptimisers.set_string_distance! — Function
set_string_distance!(; dist::StringDistances.StringDistance, min_score::Real)Set the global default of the fuzzy-suggestion settings that did_you_mean reads. The store is atomic, as ScopedConfig states. A keyword that the caller omits keeps its current default. For a temporary, task-scoped override, use with_string_distance.
Algorithm
- Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
- Build a
StringDistanceConfigfrom the two keywords. The validation below runs in that constructor. - Store it as the global default of
STRING_DISTANCEthroughset_default!.
Arguments
dist::StringDistances.StringDistance: The distance that ranks the candidate names, for exampleStringDistances.Levenshtein(),StringDistances.DamerauLevenshtein()orStringDistances.JaroWinkler().min_score::Real: The minimum normalised similarity in(0, 1]that gives a suggestion. A value above1turns all suggestions off.
Validation
min_score > 0.StringDistanceConfigchecks it. A threshold that is not positive admits every candidate with a nonzero similarity.
Returns
cfg::StringDistanceConfig: The new global default.
Related
PortfolioOptimisers.with_string_distance — Function
with_string_distance(f; dist::StringDistances.StringDistance = STRING_DISTANCE[].dist,
min_score::Real = STRING_DISTANCE[].min_score)Run f() with an override of the fuzzy-suggestion settings that did_you_mean reads, for the dynamic extent of the call. The previous settings come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.
Put this call around a meta-optimiser run, with min_score above 1, to stop the suggestions in its inner loops. Other concurrent work keeps its suggestions.
Algorithm
- Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
- Build a
StringDistanceConfigfrom the two keywords. The validation below runs in that constructor. - Run
f()withSTRING_DISTANCEbound to that value throughwith_config.
Arguments
f: The zero-argument function to run under the override.dist::StringDistances.StringDistance: The distance that ranks the candidate names.min_score::Real: The minimum normalised similarity in(0, 1]that gives a suggestion. A value above1turns all suggestions off.
Validation
min_score > 0.StringDistanceConfigchecks it.
Returns
- The value that
f()returns.
Related
PortfolioOptimisers.set_equation_limits! — Function
set_equation_limits!(; max_length::Integer, max_depth::Integer)Set the global default of the equation-parser resource caps of EQUATION_LIMITS.
Raise the caps for a large constraint set that a program wrote. Lower them to accept less untrusted input. A keyword that the caller omits keeps its current default. The store is atomic, as ScopedConfig states. For a temporary, task-scoped override, usewith_equation_limits.
Algorithm
- Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
- Build an
EquationLimitsfrom the two keywords. The validation below runs in that constructor. - Store it as the global default of
EQUATION_LIMITSthroughset_default!.
Arguments
max_length::Integer: The maximum length of an equation string that the library passes toMeta.parse.max_depth::Integer: The maximum depth of an expression tree that theExprform ofparse_equationaccepts.
Validation
max_length > 0 && max_depth > 0.EquationLimitschecks it.
Returns
lims::EquationLimits: The new global default.
Related
PortfolioOptimisers.with_equation_limits — Function
with_equation_limits(f; max_length::Integer = EQUATION_LIMITS[].max_length,
max_depth::Integer = EQUATION_LIMITS[].max_depth)Run f() with an override of the equation-parser resource caps of EQUATION_LIMITS for the dynamic extent of the call. The previous caps come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.
Use it to lower the caps around one batch of untrusted constraint strings, or to raise them for one large constraint set that a program wrote. Other concurrent work keeps its caps.
Algorithm
- Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
- Build an
EquationLimitsfrom the two keywords. The validation below runs in that constructor. - Run
f()withEQUATION_LIMITSbound to that value throughwith_config.
Arguments
f: The zero-argument function to run under the override.max_length::Integer: The maximum length of an equation string that the library passes toMeta.parse.max_depth::Integer: The maximum depth of an expression tree that theExprform ofparse_equationaccepts.
Validation
max_length > 0 && max_depth > 0.EquationLimitschecks it.
Returns
- The value that
f()returns.
Related
PortfolioOptimisers.set_log_limits! — Function
set_log_limits!(; max_warn::Union{Nothing, Integer}, max_info::Union{Nothing, Integer},
max_debug::Union{Nothing, Integer})Set the global default of the caps of LOG_LIMITS on the repeats of one log site.
Set a cap to limit how many times each site of that level logs one _id. Set it to nothing to let each site keep its own limit. A keyword that the caller omits keeps its current default. The store is atomic, as ScopedConfig states. For a temporary, task-scoped override, usewith_log_limits.
Algorithm
- Give each keyword that the caller omits the value of its field in the current global default, read atomically. The function does not read a scoped override, so the call changes the global default alone.
- Build a
LogLimitsfrom the three keywords. The validation below runs in that constructor. - Store it as the global default of
LOG_LIMITSthroughset_default!.
Arguments
max_warn: The maximum number of repeats of one_idat one@warnsite, ornothing.max_info: The maximum number of repeats of one_idat one@infosite, ornothing.max_debug: The maximum number of repeats of one_idat one@debugsite, ornothing.
Validation
- Each cap is
nothingor a positive integer.LogLimitschecks it.
Returns
lims::LogLimits: The new global default.
Related
PortfolioOptimisers.with_log_limits — Function
with_log_limits(f; max_warn::Union{Nothing, Integer} = LOG_LIMITS[].max_warn,
max_info::Union{Nothing, Integer} = LOG_LIMITS[].max_info,
max_debug::Union{Nothing, Integer} = LOG_LIMITS[].max_debug)Run f() with an override of the caps of LOG_LIMITS on the repeats of one log site, for the dynamic extent of the call. The previous caps come back when the call exits. The override is task-scoped and thread-safe, as ScopedConfig states, and the global default does not change. A keyword that the caller omits comes from the active value, so a nested override adds to the override around it.
Use it to reduce the log of one long cross-validation, while other concurrent work keeps its log. A logger counts the repeats of an _id for as long as the logger exists. A site that reached its limit inside the block thus logs nothing after the block, under the same logger.
Algorithm
- Give each keyword that the caller omits the value of its field in the active value. A nested override then starts from the override around it, and not from the global default.
- Build a
LogLimitsfrom the three keywords. The validation below runs in that constructor. - Run
f()withLOG_LIMITSbound to that value throughwith_config.
Arguments
f: The zero-argument function to run under the override.max_warn: The maximum number of repeats of one_idat one@warnsite, ornothing.max_info: The maximum number of repeats of one_idat one@infosite, ornothing.max_debug: The maximum number of repeats of one_idat one@debugsite, ornothing.
Validation
- Each cap is
nothingor a positive integer.LogLimitschecks it.
Returns
- The value that
f()returns.
Related