Update README.md (#25)

README.md

@@ -1,41 +1,75 @@
-[![](https://codecov.io/gh/delvtech/agent_0/branch/main/graph/badge.svg?token=n5y9GhZSYZ)](https://app.codecov.io/gh/delvtech/agent_0?displayType=list)
+[![](https://codecov.io/gh/delvtech/fixedpointmath/branch/main/graph/badge.svg?token=n5y9GhZSYZ)](https://app.codecov.io/gh/delvtech/fixedpointmath?displayType=list)
 [![](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![](https://img.shields.io/badge/testing-pytest-blue.svg)](https://docs.pytest.org/en/latest/contents.html)
-<br><a href="https://app.codecov.io/gh/delvtech/agent_0?displayType=list"><img height="50px" src="https://codecov.io/gh/delvtech/agent_0/branch/main/graphs/sunburst.svg?token=n5y9GhZSYZ"><a>
+<br><a href="https://app.codecov.io/gh/delvtech/fixedpointmath?displayType=list"><img height="50px" src="https://codecov.io/gh/delvtech/fixedpointmath/branch/main/graphs/sunburst.svg?token=n5y9GhZSYZ"><a>
 
-# [DELV](https://delv.tech) Agent 0
+# [DELV](https://delv.tech) FixedPoint Python repo
 
-Agent 0 monorepo with the following subpackages:
-- **agentz:** (Not Implemented) Bot specification, interface, tooling
+The FixedPoint arithmetic package provides a Python endpoint for simulationg FixedPoint arithmetic that follows standards established by the Ethereum Solidity community.
 
-- **fixedpointmath:** Fixed-point arithmetic package
 
-- **holodrive:** (Not Implemented) Plotting, visualization, post-processing of blockchain data
+## Install
 
-- **hypercache:** (Not Implemented) Accesses data from the blockchain, decodes it, and delivers it as a queryable database
+We are on [PyPI](https://pypi.org/project/fixedpointmath/):
 
-- **warpcore:** (Not implemented) Hyperdrive simulation engine (most of what is presently in elfpy)
+`pip install fixedpointmath`
 
-This project is a work-in-progress. All code is provided as is and without guarantee.
+## Testing
 
-Documentation can be found [here](https://elfpy.delv.tech).
+Testing is achieved with [py.test](https://docs.pytest.org/en/latest/contents.html).
 
-## Install
+## Contributions
 
-Please refer to [INSTALL.md](https://github.com/delvtech/agent_0/blob/main/INSTALL.md).
+Please refer to [CONTRIBUTING.md](https://github.com/delvtech/fixedpointmath/blob/main/CONTRIBUTING.md).
 
-## Build
+## Documentation
 
-Please refer to [BUILD.md](https://github.com/delvtech/agent_0/blob/main/BUILD.md).
+This numeric representation is a noiseless alternative to floating point arithmetic.
+Floating point rounding errors can be deteremental when precision matters, such as in the case of blockchain simulation.
+The `FixedPoint` conducts all operations using 18-decimal fixed-point precision integers and arithmetic.
 
-## Deployment
+### Number format
 
-TODO
+This package supports 18-decimal fixed-point precision numbers for arithmetic.
+Briefly, this means our representation for unity, "one", is `1 * 10 ** 18`, which would be `1.0` when cast to a float.
+Unlike typical floats, a FixedPoint numeric always supports 18 decimal digits of precision, regardless of the scale of the number.
 
-## Testing
+If you want the integer scaled representation, which can be useful for communicating with Solidity contracts, you must ask for it explicitly, e.g. `FixedPoint("8.52").scaled_value == 8520000000000000000`.
+Conversely, if you want to initialize a FixedPoint variable using the scaled integer representation, then you need to instantiate the variable using the `scaled_value` argument, e.g. `FixedPoint(scaled_value=8)`.
+In that example, the internal representation is `8`, so casting it to a float would produce a small value: `float(FixedPoint(scaled_value=8)) == 8e-18`.
 
-Testing is achieved with [py.test](https://docs.pytest.org/en/latest/contents.html). You can run all tests from the repository root directory by runing `python -m pytest`, or you can pick a specific test in the `tests/` folder with `python -m pytest tests/{test_file.py}`.
+If you cast FixedPoint numbers to ints or floats you will get an "unscaled" representation, e.g. `float(FixedPoint("8.0")) == 8.0` and `int(FixedPoint("8.528")) == 8`.
 
-## Contributions
+We have purposefully constrained support for mixed-type operations that include the FixedPoint type.
+Due to a lack of known precision, operations against Python floats are not allowed (e.g. `float * FixedPoint` will raise an error).
+However, operations against `int` are allowed.
+In this case, the `int` _argument_ is assumed to be "unscaled", for example `int(8) * FixedPoint(8) == FixedPoint(int(8)) * FixedPoint(8) == FixedPoint(64)`.
+The internal "scaled" representation would be `FixedPoint(64).scaled_value == 64 * 10**18`.
+
+Warning! Using floating point as a constructor to FixedPoint can cause loss of precision. For example,
+
+```
+>>> FixedPoint(1e18)
+FixedPoint("1000000000000000042.420637374017961984")
+```
+
+Allowing floating point in the constructor of FixedPoint will be removed in a future version of `fixedpointmath`.
+
+### Computing with FixedPoint
+
+The `FixedPoint` class abstracts away an internal integer representation and provides a suite of operations that act upon the class.
+For example,
+
+```python
+>>> from fixedpointmath import FixedPoint
+>>> float(FixedPoint(8.0))
+8.0
+>>> int(FixedPoint(8.528))
+8
+>>> int(8) * FixedPoint(8)
+FixedPoint("64.0")
+>>> 8.0 * FixedPoint(8)
+TypeError: unsupported operand type(s): <class 'float'>
+```
 
-Please refer to [CONTRIBUTING.md](https://github.com/delvtech/agent_0/blob/main/CONTRIBUTING.md).
+The last example throws a `TypeError` due to the lack of known precision between Python `float` and `FixedPoint`.

lib/fixedpointmath/README.md

@@ -1,30 +1,2 @@
 # fixedpointmath
-**fixedpointmath** is a package that solves the issue of noisy floating point in Python. 
-
-Floating point rounding errors can be deteremental when precision matters, such as in the case of [blockchain simulation](https://github.com/delvtech/elf-simulations). To solve this issue, we built a fixed-point class to use integers to represent real numbers. Internally, the `FixedPoint` class within **fixedpointmath** conducts all operations using 18-decimal fixed-point precision integers and arithmetic.
-
-To avoid confusion, the `FixedPoint` class abstracts the internal integer representation, and provides a suite of operations that act upon the class, including mixed-type operations. For example, 
-
-```python
->>> from fixedpointmath import FixedPoint
->>> float(FixedPoint(8.0))
-8.0
->>> int(FixedPoint(8.528))
-8
->>> int(8) * FixedPoint(8)
-FixedPoint("64.0")
->>> 8.0 * FixedPoint(8)
-TypeError: unsupported operand type(s): <class 'float'>
-```
-
-The last example throws a `TypeError` due to the lack of known precision between classic `float` and `FixedPoint`.
-
-We also provide support for accessing and initializing `FixedPoint` with the integer internal representation, which can be useful for communicating with Solidity contracts. For example,
-
-```python
->>> from fixedpointmath import FixedPoint
->>> FixedPoint(8.52).scaled_value
-8520000000000000000
->>> FixedPoint(scaled_value=int(8e18))
-FixedPoint("8.0")
-```
+**fixedpointmath** lib.