@@ -217,7 +217,7 @@ frequency, etc:
217
217
218
218
def model_update(t, x, u, params)
219
219
resp = initial_response(sys, timepts, x0) # x0 required
220
- resp = input_output_response(sys, timepts, u, x0=x0) # u required
220
+ resp = input_output_response(sys, timepts, u, x0) # u required
221
221
resp = TimeResponseData(
222
222
timepts, outputs, states=states, inputs=inputs)
223
223
@@ -301,6 +301,157 @@ Time and frequency responses:
301
301
mag, phase, omega = fresp.magnitude, fresp.phase, fresp.omega
302
302
303
303
304
+ Parameter aliases
305
+ -----------------
306
+
307
+ As described above, parameter names are generally longer strings that
308
+ describe the purpose fo the paramater. Similar to `matplotlib ` (e.g.,
309
+ the use of `lw ` as an alias for `linewidth `), some commonly used
310
+ parameter names can be specified using an "alias" that allows the use
311
+ of a shorter key.
312
+
313
+ Named parameter and keyword variable aliases are processed using the
314
+ :func: `config._process_kwargs ` and :func: `config._process_param `
315
+ functions. These functions allow the specification of a list of
316
+ aliases and a list of legacy keys for a given named parameter or
317
+ keyword. To make use of these functions, the
318
+ :func: `~config._process_kwargs ` is first called to update the `kwargs `
319
+ variable by replacing aliases with the full key::
320
+
321
+ _process_kwargs(kwargs, aliases)
322
+
323
+ The values for named parameters can then be assigned to a local
324
+ variable using a call to :func: `~config.process_param ` of the form::
325
+
326
+ var = _process_kwargs('param', param, kwargs, aliases)
327
+
328
+ where 'param` is the named parameter used in the function signature
329
+ and var is the local variable in the function (may also be `param `,
330
+ but doesn't have to be).
331
+
332
+ For example, the following structure is used in `input_output_response `::
333
+
334
+ def input_output_response(
335
+ sys, timepts=None, inputs=0., initial_state=0., params=None,
336
+ ignore_errors=False, transpose=False, return_states=False,
337
+ squeeze=None, solve_ivp_kwargs=None, evaluation_times='T', **kwargs):
338
+ """Compute the output response of a system to a given input.
339
+
340
+ ... rest of docstring ...
341
+
342
+ """
343
+ _process_kwargs(kwargs, _timeresp_aliases)
344
+ T = _process_param('timepts', timepts, kwargs, _timeresp_aliases)
345
+ U = _process_param('inputs', inputs, kwargs, _timeresp_aliases, sigval=0.)
346
+ X0 = _process_param(
347
+ 'initial_state', initial_state, kwargs, _timeresp_aliases, sigval=0.)
348
+
349
+ Note that named parameters that have a default value other than None
350
+ must given the signature value (`sigval `) so that
351
+ `~config._process_param ` can detect if the value has been set (and
352
+ issue an error if there is an attempt to set the value multiple times
353
+ using alias or legacy keys).
354
+
355
+ The alias mapping is a dictionary that returns a tuple consisting of
356
+ valid aliases and legacy aliases::
357
+
358
+ alias_mapping = {
359
+ 'argument_name_1', (['alias', ...], ['legacy', ...]),
360
+ ...}
361
+
362
+ If an alias is present in the dictionary of keywords, it will be used
363
+ to set the value of the argument. If a legacy keyword is used, a
364
+ warning is issued.
365
+
366
+ The following tables summarize the aliases that are currently in use
367
+ through the python-control package:
368
+
369
+ Time response aliases (via `timeresp._timeresp_aliases `):
370
+
371
+ .. list-table ::
372
+ :header-rows: 1
373
+
374
+ * - Key
375
+ - Aliases
376
+ - Legacy keys
377
+ - Comment
378
+ * - evaluation_times
379
+ - t_eval
380
+ -
381
+ - List of times to evaluate the time response (defaults to `timepts `).
382
+ * - final_output
383
+ - yfinal
384
+ -
385
+ - Final value of the output (used for :func: `step_info `)
386
+ * - initial_state
387
+ - X0
388
+ - x0
389
+ - Initial value of the state variable.
390
+ * - input_indices
391
+ - input
392
+ -
393
+ - Index(es) to use for the input (used in
394
+ :func: `step_response `, :func: `impulse_response `.
395
+ * - inputs
396
+ - U
397
+ - u
398
+ - Value(s) of the input variable (time trace or individual point).
399
+ * - output_indices
400
+ - output
401
+ -
402
+ - Index(es) to use for the output (used in
403
+ :func: `step_response `, :func: `impulse_response `.
404
+ * - outputs
405
+ - Y
406
+ - y
407
+ - Value(s) of the output variable (time trace or individual point).
408
+ * - return_states
409
+ - return_x
410
+ -
411
+ - Return the state when accessing a response via a tuple.
412
+ * - timepts
413
+ - T
414
+ -
415
+ - List of time points for time response functions.
416
+ * - timepts_num
417
+ - T_num
418
+ -
419
+ - Number of points to use (e.g., if `timepts ` is just the final time).
420
+
421
+ Optimal control aliases (via `optimal._optimal_aliases `:
422
+
423
+ .. list-table ::
424
+ :header-rows: 1
425
+
426
+ * - Key
427
+ - Aliases
428
+ - Comment
429
+ * - final_state
430
+ - xf
431
+ - Final state for trajectory generation problems (flatsys, optimal).
432
+ * - final_input
433
+ - uf
434
+ - Final input for trajectory generation problems (flatsys).
435
+ * - initial_state
436
+ - x0, X0
437
+ - Initial state for optimization problems (flatsys, optimal).
438
+ * - initial_input
439
+ - u0, U0
440
+ - Initial input for trajectory generation problems (flatsys).
441
+ * - initial_time
442
+ - T0
443
+ - Initial time for optimization problems.
444
+ * - integral_cost
445
+ - trajectory_cost, cost
446
+ - Cost function that is integrated along a trajectory.
447
+ * - return_states
448
+ - return_x
449
+ - Return the state when accessing a response via a tuple.
450
+ * - trajectory_constraints
451
+ - constraints
452
+ - List of constraints that hold along a trajectory (flatsys, optimal)
453
+
454
+
304
455
Documentation Guidelines
305
456
========================
306
457
@@ -625,6 +776,8 @@ processing and parsing operations:
625
776
:toctree: generated/
626
777
627
778
config._process_legacy_keyword
779
+ config._process_kwargs
780
+ config._process_param
628
781
exception.cvxopt_check
629
782
exception.pandas_check
630
783
exception.slycot_check
0 commit comments