Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit fc9fadb

Browse files
committed
add developer notes
1 parent 17b6978 commit fc9fadb

File tree

2 files changed

+155
-2
lines changed

2 files changed

+155
-2
lines changed

doc/develop.rst

Lines changed: 154 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ frequency, etc:
217217

218218
def model_update(t, x, u, params)
219219
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
221221
resp = TimeResponseData(
222222
timepts, outputs, states=states, inputs=inputs)
223223

@@ -301,6 +301,157 @@ Time and frequency responses:
301301
mag, phase, omega = fresp.magnitude, fresp.phase, fresp.omega
302302

303303

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+
304455
Documentation Guidelines
305456
========================
306457

@@ -625,6 +776,8 @@ processing and parsing operations:
625776
:toctree: generated/
626777

627778
config._process_legacy_keyword
779+
config._process_kwargs
780+
config._process_param
628781
exception.cvxopt_check
629782
exception.pandas_check
630783
exception.slycot_check

doc/optimal.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,7 @@ Plotting the results:
294294
# Simulate the system dynamics (open loop)
295295
resp = ct.input_output_response(
296296
vehicle, timepts, result.inputs, x0,
297-
t_eval=np.linspace(0, Tf, 100))
297+
evaluation_times=np.linspace(0, Tf, 100))
298298
t, y, u = resp.time, resp.outputs, resp.inputs
299299

300300
plt.subplot(3, 1, 1)

0 commit comments

Comments
 (0)