hidmic / ltitop Goto Github PK

scipy assumes zero LTI models are the result of ill conditioned numerical algorithms. The forked version of scipy that ltitop relies on works around this problem, but it's a bad approach. It's ambiguous.

Degenerate models should probably be handled separately and explicitly in ltitop.

If tree construction, crossover, and mutation ensures that all leaf nodes deal with at least one singularity, tree depth would be limited and redundant branches would be trimmed. Might even address #3 by precluding degenerate models entirely.

Description

Similarly to #14, generating HDL code (such as VHDL or Verilog) allows optimized LTI systems to be deployed to an FPGA or to be manufactured in an ASIC. Having support for HDL generation would be great.

Definition of done

TBD -- but if #14 is in place, we might be able to use bambu to generate Verilog from that C code.

Rationale

As of today, ltitop has no documentation. That makes it useless for pretty much anyone.

Definition of Done

• Document project public APIs
  • Use ReST format for docstrings.
• Document project itself
  • Add quickstart?
  • Add overview
  • Add purpose
  • Add tutorial?
• Build project documentation using Sphinx
  • Use RTD theme
• Use RTD to publish
  • Ensure rebuilds on push to master (use Github webhook).
• Populate README.md
  • Add short overview
  • Add project logo
  • Add badges
  • Link to docs

Additional considerations

See this blog post for useful pointers.

Rationale

As of today, ltitop is still pretty much a proof-of-concept. Thus, its code needs polishing, test coverage must be increased, and a continuous integration process be put in place to ensure it stays healthy over time.

Definition of Done

• Add pre-commit hooks
  • Reformat sources using black and blacken-docs
  • Reformat sources susing isort.
  • Lint sources using flake8.
  • Statically check sources using mypy.
  • Lint tox.ini using tox-ini-fmt
• Test for Python 3.5+ using tox
• Measure coverage using pytest-cov
• Configure Github Actions CI
  • Test job to ensure all unit tests pass
  • Lint job to ensure all linters pass
• Test all public APIs (~80% coverage)
• Type annotate all public APIs.

Additional considerations

Consider Codecov or Coveralls for coverage tracking.

Rationale

Alternative to #2. Algorithms are defined via sympy symbolic expressions solely to enable term permutation in summations. But such permutations would also be possible in a Python AST.

Why not ast.parse a function definition to extract its AST? Some feature (i.e. node) pruning is necessary as most Python features are way beyond scope and would be near impossible to transfer upon C or HDL generation, but otherwise this approach would greatly simplify algorithm definitions and potentially boost speed -- sympy is just too slow.

Definition of done

• Define a Python language subset to support.
  • At the very least, variables, arithmetic operators, integer literals.
• Implement a function (or decorator) to extract the AST.
• Refactor ltitop.algorithm module to deal with the new AST.
• Rewrite algorithm definitions in ltitop.topology using plain Python.

Additional considerations

Generators and list comprehensions would be super useful when defining sums and products, but, if supported, these have to be expanded upon AST extraction (or term permutation will not be possible). Also, the feature set must be kept at a minimum -- enough to guarantee that algorithms are simply describing operations on a data-flow (or code generation may not be possible).

What ltitop has right now is on shaky grounds.

Need to find a good book on modular interval arithmetic.

Rationale

For ltitop to be anything but a one-man project, some organization has to be put in place.

Definition of Done

• Add PR template
• Add issue templates
  • Add feature request template
  • Add bug report template
• Add contribution guidelines.
• Add release process.
  • Use semver for versioning.
  • Use Github releases to publish.
• Add code of conduct
• Add roadmap (as project board?)

Additional considerations

Evaluate Github Discussions for contributor exchanges.

In retrospect it was a bad call to build an ad hoc AST out of sympy symbolic expressions. Sympy's code generation infrastructure would be available if ltitop used sympy.codegen.ast data structures instead.

The ltitop.algorithms module is using sympy code generation functionality to some extent already (e.g. sympy.utilities.lambdify). Finish the job.

Worst case peak gain in ltitop is currently estimated by brute force:

Accuracy guarantees are thus quite loose, and the resulting performance is awful. It calls for a better approach.

Rationale

Distributing ltitop as a regular Python package is key to ease of use.

Requires #12 and #13.

Definition of Done

• Prepare project for proper packaging
  • Populate setup.cfg
  • Clean up setup.py
  • Add pyproject.toml
• Add project changelog.
  • Use gitchangelog to generate it
• Use PyPI to publish

Description

To actually use and validate an optimized LTI system, it has to be translated into code that can be assembled or compiled for a given processor architecture. C is by far the most common language for that purpose. Thus, putting all together, ltitop must support C code generation for a given realization or diagram.

Definition of Done

In the following, it is assumed that #9 was implemented.

• Write a function to extract a Python AST for an entire diagram.
  • Collate block ASTs as function definitions.
  • Drop repeated function definitions.
  • Capture block connections via function calls.
• Write a function to transform a Python AST into a pycparse C-AST.
  • Use an ast.NodeTransformer subclass.
• Use pycparse.c_generator.CGenerator to generate C code.
  • Toss in all necessary C preprocessor directives for compilation.

Specially when dealing with fixed point values. Arguably, this is a consequence of supporting stateful algorithms with fixed point arithmetic of arbitrary format. It probably can't be improved much for the general case, but for some cases (e.g. when using the FixedFormatArithmeticLogicUnit) it sure can be.

By moving away from plain NSGA-II, or perhaps by combining it with some niche or "island" strategy, it may be possible to distribute the search load across multiple cores. DEAP already has some examples using SCOOP. Pickling support for candidates is there.

Zero sized intervals not centered at zero are not regarded as underflow:

Should they be?